The Device Authorization Grant is designed to allow devices without a browser or with limited input capability to obtain an access token. This is useful for smart devices and command line tools.

Access tokens issued with this grant are scoped to a user. The access token will allow the bearer to access only the resources that a user has permission for.

Obtain an Access Token

1. Make a request for a Device Code

You will need to make a HTTP POST request to the https://{client}-api.bipsync.com/v1/oauth/device with the following parameters:

Parameter name	Type	Description
`client_id`	`string`	Required. The client ID assigned to your application.
`scope`	`string`	Optional. Space separated list of scopes. If this is left empty, then your access token will not be able to access API resources.

If successful the endpoint will return a JSON response like the following:

{
    "device_code": "e11b83058e3dc6042fb9dff0a1392f52961d51e2665749794a4724d929d6827fd480574491d0e753",
    "user_code": "CSTNKCJG",
    "verification_uri": "https://{client}.bipsync.com/oauth/device",
    "expires_in": 60,
    "verification_uri_complete": "https://{client}.bipsync.com/oauth/device?user_code=CSTNKCJG"
}

ℹ️
The device code expires after 60 seconds
Once the expiry time has elapsed, polling for a token will fail and a new device code will have to be generated.

2. Prompt the user to authorize the request

The user will need to open a web browser and navigate to the verification_uri_complete URI. You should display the user_code value to the user and encourage the user to compare this value to the value displayed in the web app.

This can be done on any device that the user has access to, as long as it has an internet connection and a browser that the user can sign in to the Bipsync web app with.

The user will be presented with the option to either Approve or Deny the request. The user_code value will be displayed prominently. This allows the user to cross-check the value against the value your app show, verifying that the request is legitimate.

3. Poll for an access token

Once you have a Device Code available your app should poll the Bipsync API for an access token. This involves making an HTTP POST request to https://{client}-api.bipsync.com/v1/oauth/token with the following parameters:

Parameter name	Type	Description
`grant_type`	`string`	Required Use `urn:ietf:params:oauth:grant-type:device_code` as the value.
`client_id`	`string`	Required. The client ID assigned to your application.
`device_code`	`string`	Required. The `device_code` value returned from the endpoint in step 1.

The user may not have authorized the request via the web app straight away. This means that the endpoint should be polled intermittently until either an access token is issued or a non-recoverable error is returned. A suitable delay of at least 2 seconds should be made between polling requests to avoid rate limiting.

If the endpoint returns an HTTP 400 status code it may also include an error code within the JSON response, for example:

{
  "error": "slow_down"
}

Your application should handle these error codes as follows:

Error code	Action
`slow_down`	You are making too many requests. Reduce the frequency of polling by adding a delay between requests.
`authorization_pending`	The user has not yet Approved or Denied the request. You should wait a couple of seconds then repeat the request.
`access_denied`	The user has denied the request. Polling should terminate.. An access token will not be issued and the Device Code is revoked.
`expired_token`	The Device Code has expired and has been revoked. Polling should terminate. You may want to obtain a new Device Code and ask the user to authorize it again.

If any other non-200 HTTP status code is returned, or the error does not match one of the code above, it can be assumed that the request has failed. It should not be retried with a new Device Code.

If an HTTP 200 status is returned then an access token will be issued and included in the JSON response:

{
  "token_type": "bearer",
  "expires_in": 3600,
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY...",
  "refresh_token": "def50200abf83399817830585462e876ade62cc3d07bc829582d4b4..."
}

The access token will expire after 60 minutes.