Skip to content

The v1 docs follow nauthera-server's main branch and its 0.x releases on the way to 1.0, so fields and APIs can still change.

v1

Device Authorization Request (RFC 8628)

Docs version v1 (main)Nauthera is pre-1.0, in a design-partner program

POST/device_authorization
HTTP Basic or noneRate limited

Begins the device authorization grant for browserless / input-constrained clients. Returns a device_code, a user-facing user_code, and a verification_uri; the client then polls /token with grant_type=urn:ietf:params:oauth:grant-type:device_code.

Authorization

Headers

  • Authorizationstring

    The access token, as Bearer <token> (RFC 6750 §2.1) or, for a sender-constrained token, DPoP <token> (RFC 9449 §7.1). A token minted with a cnf.jkt confirmation is only accepted together with a DPoP proof signed by that key, whichever of the two schemes carries it.

Request body

application/x-www-form-urlencoded

Device authorization request parameters (RFC 8628 §3.1).

  • client_idstring
    Example"nauthera_2Rk9"

    1–256 characters · pattern ^[!-~]+$

  • scopestring
    Example"openid profile"

    at most 2048 characters · pattern ^\S+( \S+)*$

  • resourcestring · uri

    at most 2048 characters

  • dpop_jktstring

    JWK SHA-256 thumbprint (base64url, 43 chars) binding the device session to a DPoP key (RFC 9449).

    exactly 43 characters · pattern ^[A-Za-z0-9_-]+$

  • client_secretstring

    at most 512 characters

  • client_assertion_typestring

    at most 128 characters

  • client_assertionstring

    at most 16384 characters

Responses

  • 200 OKapplication/jsonDevice and user codes to drive the flow.

    Device and user codes to drive the flow.

    Headers

    • Cache-Controlno-store

    Body

    Device authorization response (RFC 8628 §3.2).

    • device_codestringrequired

      The device verification code.

      Example"GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS"
    • user_codestringrequired

      The end-user code shown on the device.

      Example"WDJB-MJHT"
    • verification_uristring · urirequired

      Where the user enters the user_code.

      Example"https://auth.example.com/device"
    • expires_inintegerrequired

      Lifetime of the device_code / user_code in seconds.

      Example1800
    • verification_uri_completestring · uri

      verification_uri pre-filled with the user_code (for QR codes).

      Example"https://auth.example.com/device?user_code=WDJB-MJHT"
    • intervalinteger

      Minimum seconds the client must wait between /token polls.

      Example5
  • 429 Too Many Requestsapplication/problem+jsonToo many requests.

    Too many requests.

    Body

    RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the last path segment of type), so consumers can branch on it without parsing prose. type is https://nauthera.io/problems/<code>, which resolves to the code's runbook: why it happened, who is affected and what to do (RFC 9457 §3.1.1). A problem without a code has about:blank. errors is present on validation failures and lists every offending field.

    • titlestringrequired
      Example"Request validation failed"
    • statusintegerrequired
      Example400
    • typestring · uri
      Example"https://nauthera.io/problems/validation_error"
    • detailstring
      Example"One or more fields did not satisfy the API schema."
    • codeenum

      The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.

      Show more

      validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.

      Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.

      Possible values43 values
      • invalid_request
      • invalid_credentials
      • forbidden
      • unauthorized
      • insufficient_user_authentication
      • protected_account
      • password_held_by_directory
      • last_role_administrator
      • invalid_code
      • too_many_requests
      • too_many_attempts
      • account_locked
      • account_unavailable
      • already_enrolled
      • registration_disabled
      • registration_conflict
      • captcha_failed
      • invalid_reset_link
      • password_reused
      • password_too_short
      • password_too_long
      • password_compromised
      • invalid_verification_link
      • invalid_invitation_link
      • mail_relay_missing
      • email_unverified
      • not_found
      • conflict
      • unavailable
      • busy
      • window_too_large
      • too_many_series
      • internal_error
      • rate_limited
      • malformed
      • body_too_large
      • required
      • validation_error
      • unknown_org
      • invalid_token
      • invalid_dpop_proof
      • use_dpop_nonce
      • server_error
    • instancestring
      Example"/introspect"
    • request_idstring
      Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
    • trace_idstring

      Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.

      Example"4bf92f3577b34da6a3ce929d0e0e4736"
    • errorsarray of objects

      Field-level violations (present for validation errors).

      Each item:

      A single field-level validation violation.

      Show item attributes
      • fieldstringrequired

        Offending field, dotted for nested bodies (e.g. child.id).

        Example"token_type_hint"
      • codestringrequired

        Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.

        Example"not_allowed"
      • messagestringrequired
        Example"field token_type_hint must be one of [access_token, refresh_token]"
  • Errorapplication/jsonOAuth2 error response (RFC 6749 §5.2).

    OAuth2 error response (RFC 6749 §5.2).

    Headers

    • Cache-Controlno-store
    • WWW-Authenticatestring
    • DPoP-Noncestring

    Body

    An OAuth2 error response (RFC 6749 §5.2). iss (RFC 9207) is present on authorization-endpoint error responses so clients can detect mix-up.

    • errorstringrequired

      A single ASCII error code.

      Example"invalid_request"
    • error_descriptionstring
      Example"client_id, redirect_uri and response_type are required"
    • error_uristring · uri

      The error code's runbook (RFC 6749 §5.2): https://nauthera.io/runbooks/oauth/<error>.

      Example"https://nauthera.io/runbooks/oauth/invalid_request"
    • statestring

      Echoed authorization-request state (RFC 6749 §4.1.2.1).

    • issstring · uri

      Issuer identifier on authorization error responses (RFC 9207).

PreviousOAuth2 token endpointNextOAuth2 token introspection