ApplicationsInbound AppsGrant Types

Device Code Grant

The device code grant (urn:ietf:params:oauth:grant-type:device_code, RFC 8628) lets a device that can't show a login page get tokens for a user. Smart TVs, CLIs, and IoT devices are the usual cases. The device shows a short code, the user signs in on their phone or computer, and the device polls Descope until the user finishes.

Set up as an authentication method

Device code isn't a toggle under an Inbound App's Grant Types. You turn it on under Settings > Authentication Methods > Device Authentication, and devices use it with the client ID of a Federated OIDC App. For the full setup, see Device Authentication.

How It Works

  1. The device posts its client_id and scopes to the Device Authorization endpoint, /oauth2/v1/device. Descope returns a device_code, a user_code, a verification_uri (and verification_uri_complete), how long the codes last, and the polling interval.
  2. The device shows the user code and the verification URL, or a QR code that encodes verification_uri_complete.
  3. On their phone or computer, the user opens the URL. A verification Flow checks the user code, signs the user in, and asks them to approve the device.
  4. The device polls /oauth2/v1/token with grant_type=urn:ietf:params:oauth:grant-type:device_code and the device_code, waiting at least the interval between calls. Until the user finishes, Descope answers authorization_pending, or slow_down if the device polls too fast.
  5. After the user approves, Descope returns an access token, an ID token, and a refresh token. If the user denies or the codes expire, polling ends with access_denied or expired_token.
poll every intervalDeviceTV, CLI, or IoT deviceUserphone or computerDescopeauthorization server1. POST /oauth2/v1/deviceclient_id, scopedevice_code, user_code, verification_uri2. show code and URLor a QR code3. enter code, sign in, approveverification Flow4. POST /oauth2/v1/tokengrant_type=…:device_code, device_codeauthorization_pending or slow_down5. access, ID, and refresh tokens

Select any step to see what happens. The device shows a code, the user enters it somewhere else, and the device polls until they finish.

Device Code or CIBA

Both grants let a user approve a request on a different device from the one asking for tokens. They differ in how the user finds out about the request:

  • Device code: The device shows a code, and the user goes to a URL to enter it. Use it when the device has a screen the user is looking at, such as a TV or a terminal.
  • CIBA: Descope contacts the user directly, for example with an email link, and the client polls until they answer. Use it when there's no screen to show a code on, or the request comes from a backend or an agent. CIBA is an Inbound App grant.

Configure in the Console

Under Device Authentication settings, you can set:

  • Enable method in API and SDK: Device code only runs through the API and SDKs, so this toggle turns it on or off entirely.
  • User code format and characters: The pattern and character set of the code the device shows.
  • Expiration time: How long the user code and device code stay valid. The default is 3 minutes.
  • Device hosting URL: Where the verification Flow is hosted, such as Auth Hosting or your own page.
Was this helpful?

CIBA

Configure Client-Initiated Backchannel Authentication (CIBA) on a Descope Inbound App or Agentic Client for decoupled, headless user approval.

Token Exchange

Exchange a subject token for a Descope access token scoped to another Resource, governed by Policies (RFC 8693).

On this page

Device Code GrantHow It WorksDevice Code or CIBAConfigure in the ConsoleRelated