> ## Documentation Index
> Fetch the complete documentation index at: https://nevermined.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# RFC 8628 device authorization request

> Start the device flow. Requires a pre-registered client_id (BCK.OAUTH.0016) and an agent_id (absent → BCK.OAUTH.0018). Returns the device_code the agent polls with and the user_code the human approves.



## OpenAPI

````yaml /api-reference/oauth-openapi.json post /oauth/device_authorization
openapi: 3.0.0
info:
  title: Nevermined Authentication API
  description: >-
    The OAuth 2.1 + RFC 8628 device-flow ceremony and standards-based discovery
    endpoints an agent or connector uses to obtain and manage a Nevermined
    credential. These endpoints are root-mounted (not under /api/v1).
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.sandbox.nevermined.app
    description: Sandbox
  - url: https://api.live.nevermined.app
    description: Live
security: []
tags:
  - name: Authentication - Ceremony
    x-group: Ceremony
    description: Authorization Code (PKCE) and RFC 8628 device grant.
  - name: Authentication - Connections
    x-group: Connections
    description: AgentBindings — the consent receipts a user manages.
  - name: Authentication - Discovery
    x-group: Discovery
    description: RFC 8414 / 9728 / JWKS metadata.
paths:
  /oauth/device_authorization:
    post:
      tags:
        - Authentication - Ceremony
      summary: RFC 8628 device authorization request
      description: >-
        Start the device flow. Requires a pre-registered client_id
        (BCK.OAUTH.0016) and an agent_id (absent → BCK.OAUTH.0018). Returns the
        device_code the agent polls with and the user_code the human approves.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceAuthorizationRequest'
      responses:
        '200':
          description: Device + user codes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceAuthorizationResponse'
        '400':
          $ref: '#/components/responses/Error'
components:
  schemas:
    DeviceAuthorizationRequest:
      type: object
      required:
        - client_id
        - agent_id
      properties:
        client_id:
          type: string
          example: fleet
          description: Pre-registered connector (unregistered → BCK.OAUTH.0016).
        agent_id:
          type: string
          example: agent-123
          description: Target agent — required today (absent → BCK.OAUTH.0018).
        resource:
          type: string
          nullable: true
          example: https://api.nevermined.app
          description: >-
            RFC 8707 resource (audience) — SELECTS the credential. For the usual
            device-flow goal (an NVM API key), either omit it or use this API's
            host, as in the example; a NON-API resource makes the exchange mint
            an x402 permission instead, which fails with BCK.OAUTH.0008 if the
            binding has no delegation.
        scope:
          type: string
          nullable: true
          example: openid
    DeviceAuthorizationResponse:
      type: object
      properties:
        device_code:
          type: string
          description: Machine secret the agent polls with (opaque).
        user_code:
          type: string
          example: BCDF-GHJK
        verification_uri:
          type: string
          example: https://nevermined.app/oauth/device
        verification_uri_complete:
          type: string
          example: https://nevermined.app/oauth/device?user_code=BCDF-GHJK
        expires_in:
          type: integer
          example: 600
        interval:
          type: integer
          example: 5
          description: Minimum seconds between token polls.
    ErrorEnvelope:
      type: object
      properties:
        code:
          type: string
          example: BCK.OAUTH.0016
        message:
          type: string
          example: Unknown OAuth client
        category:
          type: string
          enum:
            - validation
            - auth
            - business
            - integration
            - internal
          example: auth
        hint:
          type: string
          nullable: true
        retryable:
          type: boolean
          nullable: true
          description: When present, whether retrying the same request may succeed.
        httpStatus:
          type: integer
          example: 400
  responses:
    Error:
      description: Typed error envelope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'

````

## Related topics

- [Device Flow (RFC 8628)](/docs/integrate/authentication/device-flow.md)
- [Exchange a code, device_code, or refresh_token for a credential](/docs/api-reference/authentication--ceremony/exchange-a-code-device_code-or-refresh_token-for-a-credential.md)
- [Pre-requisites](/docs/api-reference/introduction.md)
- [Authentication & Identity](/docs/integrate/authentication/overview.md)
- [Authorization Server Metadata (RFC 8414)](/docs/api-reference/authentication--discovery/authorization-server-metadata-rfc-8414.md)