OAuth 2.0 Device Authorization API

This API implements the OAuth 2.0 Device Authorization Grant (RFC 8628) for authenticating CLI tools and headless devices.

Interactive Documentation

Overview

The OAuth 2.0 Device Authorization Grant allows users to authorize CLI tools and other devices without a keyboard or browser. The flow works as follows:

1. Initiate: CLI calls POST /api/oauth/device/authorize to get device and user codes
2. User Approval: User visits verification URL in browser and approves the device
3. Poll: CLI polls POST /api/oauth/token until approved
4. Refresh: CLI uses POST /api/oauth/refresh to get new tokens when expired

Endpoints

Device Authorization

POST /api/oauth/device/authorize

Start the device authorization flow. Returns device code for polling and user code for display.

Request:

{
  "client_id": "bot-platform-cli"
}

Response:

{
  "device_code": "9f873af1f8d239823...",
  "user_code": "WDJB-MQKG",
  "verification_uri": "https://your-domain.com/auth/device",
  "verification_uri_complete": "https://your-domain.com/auth/device?code=WDJB-MQKG",
  "expires_in": 900,
  "interval": 5
}

Token Polling

POST /api/oauth/token

Poll this endpoint to check if the user has approved the device.

Request:

{
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  "device_code": "9f873af1f8d239823...",
  "client_id": "bot-platform-cli"
}

Response (approved):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 604800
}

Token Refresh

POST /api/oauth/refresh

Exchange a valid refresh token for new tokens.

Request:

{
  "grant_type": "refresh_token",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "client_id": "bot-platform-cli"
}

Authentication

• Device authorization requires client_id: "bot-platform-cli"
• Access tokens are valid for 7 days
• Refresh tokens are valid for 30 days
• All tokens use JWT (HS256) signed with BETTER_AUTH_SECRET

Rate Limiting

• Minimum 5 second interval between polling attempts
• Polling too fast returns slow_down error

Error Codes

Token Lifetimes

Next Steps

• View full interactive documentation with try-it-out functionality
• Runtime API - Bot agent runtime services
• Projects API - Project management