Device authorization

Use the device flow when an agent needs a new API key:

The agent requests a device code.
The user opens the returned verification URL, signs in, and approves the code.
The agent polls the token endpoint until it receives the API key.

The code expires after 900 seconds. Poll no more often than the returned interval value.

Start device authorization

POST /v1/auth/device

Create a pending device authorization. This endpoint needs no authentication and has no request body.

Field	Type	Description
`device_code`	string	Secret code the agent sends to the token endpoint.
`user_code`	string	Code the user enters or confirms.
`verification_uri`	string	User verification URL.
`verification_uri_complete`	string	Verification URL with the user code in its `code` query parameter.
`expires_in`	integer	Lifetime in seconds: `900`.
`interval`	integer	Minimum polling interval in seconds: `5`.
`next`	string	Instructions to show the user and agent.

Request

curl -X POST https://agentfs.cloud/v1/auth/device

Response

200 OK

{
  "device_code": "device-code-example",
  "user_code": "AB12-CD34",
  "verification_uri": "https://agentfs.cloud/device",
  "verification_uri_complete": "https://agentfs.cloud/device?code=AB12-CD34",
  "expires_in": 900,
  "interval": 5,
  "next": "Show the verification URL and code to the user, then poll the token endpoint every 5 seconds."
}

Errors

rate_limited (429), device_authorization_failed (500), internal_error (500).

Approve device authorization

POST /v1/auth/device/approve

Approve a pending user code after the user has authenticated. This endpoint uses the browser's authenticated session, not an API key. The web client calls it after the user confirms the code.

Authentication

Send the session cookie from the AgentFS web origin. Mutating cookie requests must include the web origin or an accepted same-site fetch context.

Request body

Send JSON with Content-Type: application/json.

Field	Type	Required	Description
`user_code`	string	Yes	Code returned by `POST /v1/auth/device`.
`default_project`	string	No	Existing project name to make the new key's default project.

If default_project is present, the project must already exist in the active organization. The endpoint also ensures the account's available regions before approval.

Field	Type	Description
`status`	string	Always `approved` on success.

Request

curl -X POST https://agentfs.cloud/v1/auth/device/approve \
  -H "Content-Type: application/json" \
  -H "Origin: https://agentfs.cloud" \
  -H "Cookie: <browser-session-cookie>" \
  -d '{"user_code":"AB12-CD34","default_project":"reports"}'

Response

200 OK

{
  "status": "approved"
}

Errors

csrf_rejected (403), unauthorized (401), no_active_organization (403), invalid_device_code (400 or 404), expired_device_code (400), project_not_found (404), region_unavailable (422), internal_error (500).

Exchange a device code for an API key

POST /v1/auth/device/token

Poll with the device code until the user approves it. This endpoint needs no authentication.

Request body

Send JSON with Content-Type: application/json.

Field	Type	Required	Description
`device_code`	string	Yes	Secret code returned by the start endpoint.

While the request is pending, return 428 with authorization_pending and Retry-After: 5. If you poll too soon, return 429 with slow_down and a Retry-After value containing the remaining wait in seconds.

Response fields

On approval, return:

Field	Type	Description
`type`	string	Always `account`.
`id`	string	Organization ID.
`api_key`	string	New API key. Store it as `AGENTFS_KEY`; it is not shown again.
`default_project`	string	Selected project name, or `default`.
`next`	string	Storage instruction.

A selected default_project gives the key a full-permission scope for that project. Without one, give the key full organization permissions.

Returns 200 OK after approval.

Request

curl -X POST https://agentfs.cloud/v1/auth/device/token \
  -H "Content-Type: application/json" \
  -d '{"device_code":"device-code-example"}'

Pending response

428 Authorization Pending

{
  "type": "https://agentfs.cloud/docs/errors#authorization-pending",
  "title": "authorization_pending",
  "status": 428,
  "code": "authorization_pending",
  "detail": "The device has not been approved yet.",
  "retryable": false
}

Approved response

200 OK

{
  "type": "account",
  "id": "org_1a2b",
  "api_key": "afs_example_key",
  "default_project": "reports",
  "next": "Store this value as AGENTFS_KEY. It will not be shown again."
}

Errors

invalid_device_code (400), expired_device_code (400), access_denied (403), slow_down (429), authorization_pending (428), internal_error (500).

On this page