• Starting Point of Authorization Flow.
• Request Access Token
• Use Refresh Token

Authorization Code Flow

Check the RFC6749 for a detailed flow description. This flow is intended for devices running a web browser that the user can operate interactively (e.g. Single Page Web Application or Chrome Extension).

It needs to be started in a web browser since the flow will redirect requests several times to the ezeep or even external ID providers that implement some interactive web application.

Starting Point of Authorization Flow.

To initiate the authentication the application has to start at the /oauth/authorize page with the following query parameters:

Finnaly the web browser will be redirected to the redirect URL (needs to be registered along the client ID at ezeep): <your redirect_uri>/?code=<authorization_code>

Example:

https://account.ezeep.com/oauth/authorize?response_type=code&client_id=78KYzeX5wS8r0FYz9KdvNt9xHMRA61PJK80IHwNj&redirect_uri=https://www.foo.com

Direct Response:

HTTP/1.1 301 Moved Permanently
Date: Wed, 18 Jan 2023 13:46:06 GMT
Content-Type: text/html; charset=utf-8
Content-Length: 0
Location: /oauth/authorize/?response_type=code&client_id=78KYzeX5wS8r0FYz9KdvNt9xHMRA61PJK80IHwNj&redirect_uri=https://www.ezeep.com

If you are not already signed in to your ezeep account you will be asked to sign in.

After successful authentication you will be redirected to the relevant url with the authorization code as a url parameter

- `<your redirect_uri>/?code=<authorization_code>`

Example URL finnaly redirected to: shell https://www.foo.com/?code=UWvSbESYQ2SirrvPCoasSRVYK6jDDD

Request Access Token

Now that you have an Authorization Code, you must exchange it for tokens. Using the extracted Authorization Code (code) from the previous step. For all following requests mentioned in this article you will need an Authorization HTTP(S) header value.

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=authorization_code" \
      --data "scope=printing reporting" \
      --data "code=<authorization_code>" \
      --data "redirect_uri=<your redirect_uri>"

Example Response

{
  "access_token": "eyJ0eXAiO...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "printing reporting",
  "refresh_token": "erliDdAb..."
}

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:

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=refresh_token" \
     --data "scope=printing reporting" \
     --data "refresh_token=qX5HTLt4..."

Example Response

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

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