Orbit Device API
RFC 8628 device-authorization flow — how CLIs mint their first token
RFC 8628 device-authorization flow — how CLIs mint their first token
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/orbitapps-io:orbitapps-io-device-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Orbit Apps Device API
version: 1.0.0
description: Public REST API for Orbit Apps.
servers:
- url: https://api.orbitapps.io
description: Production
security:
- bearerAuth: []
tags:
- name: Device
description: RFC 8628 device-authorization flow — how CLIs mint their first token
paths:
/api/v1/device/token:
post:
requestBody:
content:
application/x-www-form-urlencoded:
schema:
oneOf:
- title: OAuthDeviceTokenRequest
type: object
properties:
grant_type:
type: string
device_code:
type: string
client_id:
type: string
minLength: 1
maxLength: 64
additionalProperties: false
- type: 'null'
responses:
'200':
description: The minted token — shown exactly once. Manage it afterwards via /api/v1/tokens/{id}.
content:
application/json:
schema:
anyOf:
- title: DeviceTokenResponse
description: The minted api token — shown exactly once, exactly here.
type: object
properties:
token:
description: The bearer token plaintext. Store it securely; it is not retrievable again.
type: string
token_id:
description: The token row's id — manage it via /api/v1/tokens/{id}.
type: string
format: uuid
scope:
description: profile | org, from the approval.
type: string
kind:
description: Always `live`.
type: string
required:
- token
- token_id
- scope
- kind
additionalProperties: false
- title: OAuthDeviceTokenResponse
type: object
properties:
access_token:
type: string
token_type:
const: Bearer
scope:
type: string
required:
- access_token
- token_type
- scope
additionalProperties: false
'400':
description: 'RFC 8628 flow state: authorization_pending | slow_down | access_denied | expired_token | invalid_grant.'
content:
application/json:
schema:
title: DeviceFlowError
description: 'RFC 8628 error vocabulary: authorization_pending (keep polling), slow_down (poll slower), access_denied (user denied), expired_token (grant expired or already claimed — restart the flow), invalid_grant (unknown/forged device_code).'
type: object
properties:
error:
type: string
required:
- error
additionalProperties: false
tags:
- Device
summary: Poll for the minted token
description: 'Polls the grant. While the user hasn''t acted: 400 `authorization_pending` — keep polling every `interval` seconds (polling faster earns `slow_down`). Once approved, THIS call mints the api token and returns it — exactly once; the grant is then `claimed` and further polls answer `expired_token`.
Terminal errors: `access_denied` (user declined), `expired_token` (grant older than 15 minutes or already claimed — restart the flow), `invalid_grant` (unknown/forged device_code).
Errors use RFC 8628''s bare `{error}` vocabulary, not problem+json, so standard device-flow clients work unmodified.'
security: []
operationId: postApiV1DeviceToken
x-operation-id-source: derived
/api/v1/device/code:
post:
requestBody:
content:
application/x-www-form-urlencoded:
schema:
oneOf:
- title: OAuthDeviceCodeRequest
type: object
properties:
client_id:
type: string
minLength: 1
maxLength: 64
scope:
type: string
additionalProperties: false
- type: 'null'
responses:
'200':
description: The grant. Show user_code, then poll /device/token every `interval` seconds.
content:
application/json:
schema:
title: DeviceCodeResponse
description: RFC 8628 device authorization response.
type: object
properties:
device_code:
description: Secret the device polls /device/token with. Never show it to the user.
type: string
user_code:
description: Human-typable code the user enters in Studio, shaped XXXX-XXXX.
type: string
verification_uri:
description: Where the user approves the grant.
type: string
verification_uri_complete:
description: Same, with the user_code pre-filled — render as a link or QR.
type: string
expires_in:
description: Grant lifetime in seconds (15 minutes).
type: integer
interval:
description: Minimum seconds between /device/token polls.
type: integer
required:
- device_code
- user_code
- verification_uri
- verification_uri_complete
- expires_in
- interval
additionalProperties: false
tags:
- Device
summary: Start a device-authorization grant
description: 'Begins the RFC 8628 device flow: returns a secret `device_code` (poll with it) and a human-typable `user_code` (show it, or render `verification_uri_complete` as a link/QR). The user approves at the verification URI in Studio, choosing the token''s scope (personal, or one of their orgs).
Anonymous — this is how a CLI gets its first token. Grants expire after 15 minutes.'
security: []
operationId: postApiV1DeviceCode
x-operation-id-source: derived
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: opaque
description: 'An Orbit api token, sent as `Authorization: Bearer <token>`.
Mint one with the RFC 8628 device-authorization grant (`POST /api/v1/device/code`, then poll `POST /api/v1/device/token`), or from Studio.
Every token carries a scope set from the `[verb resource]` RBAC catalog — `read:app`, `write:deployment`, `manage:secret`, and so on. The full vocabulary is published as `scopes_supported` at `/.well-known/oauth-protected-resource` (RFC 9728) and `/.well-known/oauth-authorization-server` (RFC 8414). Grant an agent the narrowest set that does its job.'
externalDocs:
description: Full documentation
url: https://docs.orbitapps.io
x-id:
- reitit.openapi/default