Orbit Device API

RFC 8628 device-authorization flow — how CLIs mint their first token

GitHub OpenAPI

Operations 2

POST /api/v1/device/token Poll for the minted token #
POST /api/v1/device/code Start a device-authorization grant #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/orbitapps-io:orbitapps-io-device-api"
All apis
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.

Get an API 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 Specification

orbitapps-io-device-api-openapi.yml Raw ↑
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