• Requesting Authorization Code
• Login into Authorization URL
• Getting Access Token from Pairing Code
• Use Refresh Token

Device Authorization Flow

Check the RFC8628 for a detailed flow description. This flow is intended for Internet-connected devices that either lack a browser to perform a user-agent-based authorization or are input constrained to the extent that requiring the user to input text in order to authenticate during the authorization flow is impractical.

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

1. Getting pairing code (e.g. on some headless device).
2. Logging in to ezeep using the authorization url and code gotten from 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).

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

Requesting Authorization Code

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

Supported attributes:

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

Example Request

curl  -X POST "https://account.ezeep.com/oauth/pair/" \
      --header "Authorization: Basic NzhLWXplWDV3UzhyMEZZejlLZHZOdDl4SE1SQTYxUEpLODBJSHdOajo=" \
      --data "{
            \"scope\":\"printing\",
            \"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.

Login into 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.

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

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:

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

Example Request

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

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. Usually, a user will need a new access_token only after the previous one expires or when gaining access to a new resource (with extended/different scope) for the first time. It’s bad practice to call the endpoint to get a new access_token every time you call an API, rate limiting for this endpoint may be applied.

According to RFC7009, a client should revoke the refresh token when no longer needed. This allows the authorization server to clean up security credentials. A revocation request will invalidate the actual refresh token and, if applicable, other refresh tokens based on the same authorization grant. Check the Token Revocation Article or RFC7009 for a detailed description.

To refresh your token, make a POST request to the /oauth/token endpoint in the Authentication API, using grant_type=refresh_token

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

Supported attributes:

Example Request

curl -X POST "https://account.ezeep.com/oauth/access_token/" \
     --header "Authorization: Basic NzhLWXplWDV3UzhyMEZZejlLZHZOdDl4SE1SQTYxUEpLODBJSHdOajo=" \
     --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.