Authorization Code Flow

Check the RFC6749 for a detailed flow description. This flow is intended for confidential clients, such as server-side applications that can keep a client secret. Public clients (mobile, desktop, single-page and CLI applications) use the Authorization Code Flow with PKCE.

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:

Attribute	Type	required	description
`response_type`	string	Yes	defines the OAuth2 grant, needs to be `code`
`client_id`	string	Yes	the Client ID you received from ezeep
`redirect_uri`	string	Yes	Must match one of the redirect URIs you provided when you requested your Client ID (URL-encoded)
`social`	string	No	`azure` to automatically redirect to Microsoft for authentication
`prompt`	string	No	`none`: neither ezeep nor Microsoft shows a login prompt if a user session already exists, see Implicit login for Azure AAD based accounts
`scope`	string	No	`printing` (space separated scope list)
`state`	string	No	can be used to maintain state after redirecting the user agent

Finally 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>&state=<state>

Example:

https://account.ezeep.com/oauth/authorize/?response_type=code&client_id=<client_id>&redirect_uri=https%3A%2F%2Fwww.example.com%2Fcallback&state=8b1a59d6af933215414d332b1dabb095

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.

Example URL finally redirected to: shell https://www.example.com/callback?code=UWvSbESYQ2SirrvPCoasSRVYK6jDDD&state=8b1a59d6af933215414d332b1dabb095

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:

Attribute	Type	Required	Description
`Authorization`	HTTP Header	yes	Basic {{base_64_encoded_client_id_and_secret}}
`Content-Type`	HTTP Header	yes	`application/x-www-form-urlencoded`
`grant_type`	string	yes	`authorization_code`
`scope`	string	no	`printing reporting` (space separated scope list); can only narrow the granted scopes
`code`	string	yes	code passed to call to redirect URL
`redirect_uri`	string	yes	`<your redirect_uri>`

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	[optionally] 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_and_secret>" \
      --header "Content-Type: application/x-www-form-urlencoded" \
      --data "grant_type=authorization_code" \
      --data "scope=printing reporting" \
      --data "code=<authorization_code>" \
      --data-urlencode "redirect_uri=https://www.example.com/callback"

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. 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_and_secret}}
`Content-Type`	HTTP Header	yes	`application/x-www-form-urlencoded`
`grant_type`	string	yes	`refresh_token`
`scope`	string	no	`printing reporting` (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/

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_and_secret>" \
     --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.