Skip to main content
The Superserve API uses Bearer token authentication. All authenticated requests must include an Authorization header with your API token.

​
Authentication Header

Authorization: Bearer YOUR_API_TOKEN

​
Get API Token

You can obtain an API token by running the CLI login command: 
superserve login
The token is stored locally at ~/.superserve/auth.json and used automatically by the CLI and SDK.

​
Device Code Flow

The device code flow allows users to authenticate via a web browser. This is the method used by superserve login.

​
Initiate Device Code Flow

POST /v1/auth/device-code
Content-Type: application/json
Response:
​
device_code
string
required
Device code to poll for authentication status
​
user_code
string
required
Human-readable code to display to the user
​
verification_uri
string
required
URL where the user should authenticate
​
verification_uri_complete
string
required
Full URL with user code pre-filled
​
expires_in
number
required
Number of seconds until the device code expires
​
interval
number
required
Minimum number of seconds to wait between polling requests
Example Response: 
{
  "device_code": "DEVICE_CODE_HERE",
  "user_code": "ABCD-1234",
  "verification_uri": "https://console.superserve.ai/device",
  "verification_uri_complete": "https://console.superserve.ai/device?code=ABCD-1234",
  "expires_in": 900,
  "interval": 5
}

​
Poll for Token

After initiating the device code flow, poll this endpoint to check if the user has completed authentication. 
POST /v1/auth/device-token
Content-Type: application/json
Request Body:
​
device_code
string
required
Device code from the initial response
Success Response:
​
access_token
string
Access token (may be named token instead)
​
token
string
Access token (alternative field name)
​
expires_at
string | null
ISO 8601 timestamp when the token expires
​
refresh_token
string | null
Refresh token for obtaining new access tokens
Pending/Error Response:
​
error
string
Error code: authorization_pending, slow_down, expired_token, or access_denied
​
error_description
string
Human-readable error description
Example Success: 
{
  "access_token": "your-api-token",
  "expires_at": "2026-04-09T12:00:00Z",
  "refresh_token": null
}
Example Pending: 
{
  "error": "authorization_pending",
  "error_description": "User has not completed authorization"
}

​
Error Codes

CodeStatusDescription
authorization_pending428User hasn’t completed authentication yet
slow_down400Polling too frequently, wait longer
expired_token410Device code has expired
access_denied403User denied the authentication request

​
Validate Token

Check if your current token is valid. 
GET /v1/auth/validate
Authorization: Bearer YOUR_API_TOKEN
Response:
​
valid
boolean
Whether the token is valid
​
user
object | null
User information if token is valid
Example: 
{
  "valid": true,
  "user": {
    "id": "usr_abc123",
    "email": "[email protected]",
    "full_name": "Jane Doe"
  }
}

​
Get Current User

Retrieve information about the authenticated user. 
GET /v1/auth/me
Authorization: Bearer YOUR_API_TOKEN
Response:
​
id
string
required
User ID
​
email
string
required
User email address
​
full_name
string | null
User’s full name
Example: 
{
  "id": "usr_abc123",
  "email": "[email protected]",
  "full_name": "Jane Doe"
}

​
Error Responses

All authentication endpoints may return these errors:
​
status
number
HTTP status code
​
detail
string
Error message
​
details
object
Additional error context
Common Errors:
StatusMessage
401Not authenticated. Run superserve login first.
403Access denied by user
410Device code expired
428Authorization pending

Build docs developers (and LLMs) love

Get started for freeTalk to us