Device Authorization Flow

This flow uses the ezeep pairing_code grant. It is similar to the OAuth 2.0 Device Authorization Grant (RFC8628) but does not implement it. It is intended for devices that have no web browser or only limited input: the user signs in with a web browser on another device.

Getting an access token from the pairing device flow method consists of 3 steps.

  1. Getting pairing code (e.g. on some headless device).
  2. Logging in to ezeep using the authorization url and code obtained in step 1 (on any device a web browser is running on).
  3. Getting the access token with the pairing code (on the device used for step 1).

Flow diagram of device code flow

For all request mentioned in this article you will need an Authorization HTTP(S) header value.

Requesting Pairing Code 

POST https://account.ezeep.com/oauth/pair/

Supported attributes:

Attribute Type Required Description
Authorization HTTP Header Yes Basic {{base_64_encoded_client_id}}
Content-Type HTTP Header Yes ‘application/x-www-form-urlencoded’
mode string Yes ‘user’ or ‘device’
scope string No printing (space separated scope list)
hardware_id string No for device token only: stick to a device guid

If successful, returns HTTP status code and the following response attributes:

Attribute Type Description
pairing_code string some pairing code the user may enter during the authorization process in browser
auth_url string start URL of the authorization process

Example Request

curl  -X POST "https://account.ezeep.com/oauth/pair/" \
      --header "Authorization: Basic <base64_encoded_client_id>" \
      --header "Content-Type: application/x-www-form-urlencoded" \
      --data "scope=printing" \
      --data "mode=device"

Example Response

{
  "pairing_code": "uafdHUwAs7",
  "auth_url": "https://account.ezeep.com/auth/signin/?next=%2Foauth%2Fauthorize%2Fpairing%2F%3Fpairing_code%3DuafdHUwAs7&device=generic"
}

pairing_code : is the unique code for the device. When the user goes to the auth_url in their browser-based device, this code will be bound to their session.

auth_url : contains the URL the user should visit on some device running a web browser to authorize the device.

Log in to the Authorization URL

After getting the auth_url in the previous step, open the auth_url in a web browser on any device will start the user authentication process, the user may be asked for the pairing code during that process.


signing in to your account

  • sign in to your account, you will be redirected to the successful login page


successful sign in into your account

Getting Access Token from Pairing Code

Meanwhile the process running on the device will poll for an access/refresh token

POST https://account.ezeep.com/oauth/access_token/

Supported attributes:

Attribute Type Required Description
Authorization HTTP Header Yes Basic {{base_64_encoded_client_id}}
Content-Type HTTP Header Yes application/x-www-form-urlencoded
grant_type string Yes pairing_code
scope string No printing (space separated scope list)
pairing_code string Yes the formerly obtained pairing_code

If successful, returns HTTP status code 200 OK and the following response attributes:

Attribute Type Description
access_token string the access token that is required in Authorization header of API requests
token_type string for ezeep always “Bearer”, has to be passed in Authorization header
expires_in int validity time in seconds of the access token
scope string scope(s) of token
refresh_token string refresh token, to be used for getting a new access token


Example Request

curl  -X POST "https://account.ezeep.com/oauth/access_token/" \
      --header "Authorization: Basic <base64_encoded_client_id>" \
      --header "Content-Type: application/x-www-form-urlencoded" \
      --data "grant_type=pairing_code" \
      --data "scope=printing" \
      --data "pairing_code=uafdHUwAs7"


Example Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FjY291bnQu...u0oEBY34y2Im39-l6PtCEHXor3xEpnBKAOPh72QQ",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "printing",
  "refresh_token": "F2UuSA...zrhg15MA"
}

The access_token will be valid for 3600 seconds (i.e. 1 hour) and after that duration you have to request new access token using the refresh token that you received in the access token response.

Use Refresh Token

You can use the refresh_token to get a new access_token. Reuse the access token until it expires; do not request a new access token for every API call. Rate limiting may be applied to this endpoint.

Revoke the refresh token when your application no longer needs it, see Token Revocation.

To refresh your token, send a POST request to /oauth/access_token/ with grant_type=refresh_token.

curl -X POST https://account.ezeep.com/oauth/access_token/

Supported attributes:

Attribute Parameter Type Required Description
Authorization HTTP Header yes Basic {{base_64_encoded_client_id}}
Content-Type HTTP Header yes application/x-www-form-urlencoded
grant_type string yes refresh_token
scope string no printing (space separated scope list); can only narrow the granted scopes
refresh_token string yes refresh_token obtained by last (token rotation) call to /oauth/access_token/

Example Request

curl -X POST "https://account.ezeep.com/oauth/access_token/" \
     --header "Authorization: Basic <base64_encoded_client_id>" \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data "grant_type=refresh_token" \
     --data "scope=printing" \
     --data "refresh_token=qX5HTLt4..."

Example Response

{
  "access_token": "eyJ0eXAiOiJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "printing",
  "refresh_token": "vT5GTKk8..."
}

You will need to replace and store the new refresh token securely from the response for future usage.