Authentication
The Roboticks API supports multiple authentication methods for different use cases.
Authentication Methods
| Method | Use Case | Token Type |
|---|
| JWT Token | Web app, short-lived sessions | Bearer token |
| API Key | CI/CD, automation, long-lived access | API key |
API Key Authentication
API keys are recommended for automation and CI/CD pipelines.
Creating an API Key
- Go to Settings > API Keys in the Roboticks web app
- Click Create API Key
- Enter a descriptive name
- Copy the key (it won’t be shown again)
Using API Keys
Include the API key in the Authorization header:
curl -H "Authorization: Bearer rbtk_xxxxxxxxxxxxxxxx" \
https://api.roboticks.io/api/v1/organizations/acme/devices
X-API-Key header:
curl -H "X-API-Key: rbtk_xxxxxxxxxxxxxxxx" \
https://api.roboticks.io/api/v1/organizations/acme/devices
API Key Permissions
API keys inherit the permissions of the user who created them. Keys can access:
- Organizations the user belongs to
- Projects the user has access to
- Resources within those projects
API Key Best Practices
Never commit API keys to version control or share them in plain text.
- Use environment variables in CI/CD
- Rotate keys regularly (at least quarterly)
- Use descriptive names to track usage
- Delete unused keys promptly
- Create separate keys for different systems
JWT Token Authentication
JWT tokens are used by the web app and CLI for interactive sessions.
Obtaining a Token
Use the CLI login flow:
Or authenticate via the API:
POST /api/v1/auth/login
Content-Type: application/json
{
"email": "user@example.com",
"password": "your-password"
}
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer",
"expires_in": 3600
}
Using JWT Tokens
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
https://api.roboticks.io/api/v1/organizations/acme/devices
Token Refresh
Tokens expire after 1 hour. Refresh before expiration:
POST /api/v1/auth/refresh
Authorization: Bearer YOUR_CURRENT_TOKEN
Organization and Project Context
Most API endpoints require organization and project context in the URL:
/api/v1/organizations/{org_slug}/projects/{project_slug}/devices
GET /api/v1/organizations/acme/projects/warehouse/devices
Rate Limiting
Rate limits are applied per API key or user:
| Response Header | Description |
|---|
X-RateLimit-Limit | Maximum requests per window |
X-RateLimit-Remaining | Remaining requests |
X-RateLimit-Reset | Unix timestamp when limit resets |
429 response:
{
"detail": "Rate limit exceeded. Try again in 60 seconds.",
"retry_after": 60
}
Error Handling
401 Unauthorized
Token is missing, invalid, or expired:
{
"detail": "Could not validate credentials"
}
403 Forbidden
Valid credentials but insufficient permissions:
{
"detail": "Not enough permissions"
}
Code Examples
import requests
API_KEY = "rbtk_xxxxxxxxxxxxxxxx"
BASE_URL = "https://api.roboticks.io/api/v1"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
# List devices
response = requests.get(
f"{BASE_URL}/organizations/acme/projects/warehouse/devices",
headers=headers
)
devices = response.json()
const API_KEY = "rbtk_xxxxxxxxxxxxxxxx";
const BASE_URL = "https://api.roboticks.io/api/v1";
// List devices
const response = await fetch(
`${BASE_URL}/organizations/acme/projects/warehouse/devices`,
{
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json"
}
}
);
const devices = await response.json();
API_KEY="rbtk_xxxxxxxxxxxxxxxx"
curl -X GET \
"https://api.roboticks.io/api/v1/organizations/acme/projects/warehouse/devices" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json"
Next Steps
Fleet API
Manage devices with the Fleet API
