Authentication
The Teradek REST API uses OAuth 2.0 with the Resource Owner Password Credentials grant (RFC 6749) for authentication.
Get an Access Token
Request an access token using your device admin password:
POST /oauth/token
curl -X POST https://<device-ip>/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password&password=<admin-password>"| Parameter | Type | Required | Description |
|---|---|---|---|
grant_type | string | Yes | Must be password |
password | string | Yes | Device admin password |
Response
{
"expires_in": 3600,
"token_type": "Bearer",
"refresh_token": "bNLzvBOEqwDNYApV9jduhjlVXIoOp9kB",
"access_token": "rYDVtxfHdH7Igk5qdMEWMJZAJpg1Gjvy"
}Refresh an Access Token
Use a refresh token to obtain a new access token without re-authenticating:
POST /oauth/token
curl -X POST https://<device-ip>/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token&refresh_token=<your-refresh-token>"| Parameter | Type | Required | Description |
|---|---|---|---|
grant_type | string | Yes | Must be refresh_token |
refresh_token | string | Yes | The refresh token from initial auth |
Using the Token
Include the access token in the Authorization header for all API requests:
Authorization Header
Authorization: Bearer <access_token>Token Expiration
Tokens have a limited lifetime. Use the refresh token to obtain new access tokens before they expire. All tokens are invalidated if the device password is changed.
| Token Type | Expiration |
|---|---|
| Access Token | 1 hour |
| Refresh Token | 1 week |
Rate Limiting
The API enforces rate limits to protect device resources. Exceeding the limit returns a 429 status code.
| Endpoint Type | Limit | Window |
|---|---|---|
| API endpoints | 60 requests | 60 seconds |
| OAuth endpoints | 30 requests | 60 seconds |
Rate Limit Headers
Rate limit information is included in response headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed |
X-RateLimit-Remaining | Requests remaining in window |
X-RateLimit-Reset | Unix timestamp when window resets |
HTTP Status Codes
| Code | Description |
|---|---|
| 200 | Success |
| 400 | Bad Request -- Invalid input |
| 401 | Unauthorized -- Missing or invalid token |
| 429 | Too Many Requests -- Rate limit exceeded |
| 500 | Internal Server Error |