Call Your API Using the Device Authorization Flow

• Authentication API: Keep reading to learn how to call our API directly. For an interactive experience, read Device Flow Playground.

​

Prerequisites

• Check limitations (below) to be sure the Device Authorization flow is suitable for your implementation.
• Register the Application with Auth0.
  • Select an Application Type of Native.
  • If necessary, set Allowed Web Origins. You can use this to allow localhost as an origin for local development, or to set an allowed origin for specific TV software with architecture subject to CORS (e.g., HTML5 + JS). Most applications will not use this setting.
  • Ensure that the OIDC Conformant toggle is enabled. This setting is in the Dashboard under Applications > Application > Advanced Settings > OAuth.
  • Make sure the Application’s Grant Types include Device Code. To learn how, read Update Grant Types.
  • If you want your Application to be able to use Refresh Tokens, make sure the Application’s Grant Types include Refresh Token. To learn how, read Update Grant Types. To learn more about Refresh Tokens, read Refresh Tokens.
• Set up and enable at least one connection for the Application: Database connections, Social connections
• Register your API with Auth0
  • If you want your API to receive Refresh Tokens to allow it to obtain new tokens when the previous ones expire, enable Allow Offline Access. To learn more about Refresh Tokens, read Refresh Tokens.
• Configure Device User Code Settings to define the character set, format, and length of your randomly-generated user code.

​

Steps

1. Request device code (Device Flow): Request a device code that the user can use to authorize the device.
2. Request device activation (Device Flow): Request that the user authorize the device using their laptop or smartphone.
3. Request tokens (Device Flow): Poll the token endpoint to request a token.
4. Authorize user (Browser Flow): The user authorizes the device, so the device can receive tokens.
5. Receive tokens (Device Flow): After the user successfully authorizes the device, receive tokens.
6. Call API (Device Flow): Use the retrieved Access Token to call your API.
7. Refresh tokens (Device Flow): Use a Refresh Token to request new tokens when the existing ones expire.

​

Request device code

​

Example POST to device code URL

curl --request POST \
  --url 'https://{yourDomain}/oauth/device/code' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'client_id={yourClientId}' \
  --data 'scope={scope}' \
  --data 'audience={audience}'

Device code parameters

• must include an audience parameter
• can include additional scopes supported by the target API

​

Device code response

{
  "device_code": "Ag_EE...ko1p",
  "user_code": "QTZL-MCBW",
  "verification_uri": "https://accounts.acmetest.org/activate",
  "verification_uri_complete": "https://accounts.acmetest.org/activate?user_code=QTZL-MCBW",
  "expires_in": 900,
  "interval": 5
}

• device_code is the unique code for the device. When the user goes to the verification_uri in their browser-based device, this code will be bound to their session.
• user_code contains the code that should be input at the verification_uri to authorize the device.
• verification_uri contains the URL the user should visit to authorize the device.
• verification_uri_complete contains the complete URL the user should visit to authorize the device. This allows your app to embed the user_code in the URL, if you so choose.
• expires_in indicates the lifetime (in seconds) of the device_code and user_code.
• interval indicates the interval (in seconds) at which the app should poll the token URL to request a token.

​

Request device activation

​

Request tokens

​

Example request token POST to token URL

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=urn:ietf:params:oauth:grant-type:device_code \
  --data 'device_code={yourDeviceCode}' \
  --data 'client_id={yourClientId}'

Token request parameters

​

Token responses

Authorization pending

HTTP/1.1 403 Forbidden
{
  "error": "authorization_pending",
  "error_description": "..."
}

Slow down

HTTP/1.1 429 Too Many Requests
{
  "error": "slow_down",
  "error_description": "..."
}

Expired token

HTTP/1.1 403 Bad Request
{ 
  "error": "expired_token",
  "error_description": "..."
}

Access denied

HTTP/1.1 403 Forbidden
{
  "error": "access_denied",
  "error_description": "..."
}

• the user refused to authorize the device
• the authorization server denied the transaction
• a configured rule denied access (To learn more, read Auth0 Rules.)

​

Authorize user

• Authenticating the user;
• Redirecting the user to an Identity Provider to handle authentication;
• Checking for active SSO sessions;
• Obtaining user consent for the device, unless consent has been previously given.

​

Receive tokens

{
  "access_token":"eyJz93a...k4laUWw",
  "refresh_token":"GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type":"Bearer",
  "expires_in":86400
}

​

Call your API

curl --request GET \
  --url https://myapi.com/api \
  --header 'authorization: Bearer ACCESS_TOKEN' \
  --header 'content-type: application/json'

​

Refresh tokens

• configured your API to allow offline access
• included the offline_access scope when you initiated the authentication request through the authorize endpoint

​

Example refresh token POST to token URL

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=refresh_token \
  --data 'client_id={yourClientId}' \
  --data 'client_secret={yourClientSecret}' \
  --data 'refresh_token={yourRefreshToken}'

Refresh token request parameters

​

Refresh token response

{
  "access_token": "eyJ...MoQ",
  "expires_in": 86400,
  "scope": "openid offline_access",
  "id_token": "eyJ...0NE",
  "token_type": "Bearer"
}

​

Sample use cases

​

Detect device authorization flow use

function (user, context, callback) {
   if (context.protocol === 'oauth2-device-code') {
      ...
   }
 
   callback(null, user, context);
}

​

Sample implementations

• Device Authorization Playground
• AppleTV (Swift): Simple application that shows how Auth0 can be used with the Device Authorization Flow from an AppleTV.
• CLI (Node.js): Sample implementation of a CLI that uses the Device Authorization Flow instead of the Authorization Code Flow. The major difference is that your CLI does not need to host a web server and listen on a port.

​

Troubleshoot

​

Error codes

​

Limitations

• Support Server Name Indication (SNI) when Custom Domains are used
• Have an Auth0 application type of Native
• Have the Token Endpoint Authentication Method set to None
• Be OIDC-conformant
• Not be created through Dynamic Client Registration

• Social Connections using Auth0 developer keys unless you are using the Universal Login experience
• Query string parameters to be accessed from hosted login page or Rules or Actions
• User account linking

​

Learn more

• OAuth 2.0 Authorization Framework
• OpenID Connect Protocol
• Tokens
• Logs