Device Flow Grant

OAuth 2.0

Device Flow Grant

This grant is for devices that do not have a browser capable of making secure connections for a user. Instead, a 8 character code is generated which the user will enter into another device's browser to pair an account to the device. The implementation is based on this specification. A use case for this flow is a user authorizing a smart TV to access Pandora APIs on their behalf. Instead of typing their username and password into the TV (e.g. using the remote control) they can enter the device code into a browser on their computer or smartphone to authorize the smart TV.

1. Generate and display the device code

The device backend sends a POST request to https://www.pandora.com/oauth/v1/device with the content type application/x-www-form-urlencoded and the following parameters:

Parameter	Description	Type	Example	Required
`scope`	A space delimited list of scopes the client would like. Only “webapi” is supported for now. The default is also “webapi”.	string	"webapi"	No

Additionally, the client should include a basic authentication header that looks like the following

Authorization: Basic Base64Encode(client_id:client_secret)

The authorization server responds with a JSON object that contains:

Field	Description
`device_code`	A long identifier for the device flow session, used to poll the token endpoint.
`user_code`	The 8 character code presented to the user, who will enter the code at the activation URL in their browser.
`verification_uri`	The URL at which the user should open in their browser.
`verification_uri_complete`	The URL at which the user should open in their browser with the user code pre-populated.
`expires_in`	The time in seconds the device flow authorization session must be completed in.
`interval`	The number of seconds between polling requests made to the token endpoint until the authorization session expires.

The device itself should then display the verification URI and user code to the user, indicating that they must sign in to their account on another device.

You can use this curl command to test:



curl 'https://www.pandora.com/oauth/v1/device' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic Base64Encode(client_id:client_secret)'

2. Wait for user to complete authorization

While displaying the verification URI and user code to the user, the device should poll at the specified interval to see if the user has finished authorizing the device. This polling request should be made to https://www.pandora.com/oauth/v1/token with the content type application/x-www-form-urlencoded and parameters:

Parameter	Description	Type	Required
`grant_type`	Must be set to urn:ietf:params:oauth:grant-type:device_code	string	Yes
`device_code`	The device_code value from the previous /oauth/v1/device payload.	string	Yes
`client_id`	The value used in the /oauth/v1/device authorization header.	string	Yes

Until the user actually logs in and associates the user_code with their account, the response to this request will a JSON object and 400 Bad Request status code:

error with the value authorization_pending

If the user takes too long to authorize and the device code expires, the response to this request will a JSON object and 400 Bad Request status code:

error with the value expired_token

The authorization server responds with a JSON object that contains:

Parameter	Description
`token_type`	The value "Bearer"
`expires_in`	The time in seconds the token is valid for.
`access_token`	The access token that can be used to access a Pandora protected resource.
`refresh_token`	A token that can be used at the refresh endpoint to fetch a fresh access_token.

3. Refresh the access token

Use the refresh token grant as needed to generate new access tokens.