Refresh Token

Refresh Tokens are issued to the Client by the Authorization Server and are used to obtain a new Access Token when the current Access Token becomes invalid or expires, or to obtain additional Access Tokens with identical or narrower scope (Access Tokens may have a shorter lifetime and fewer permissions than authorized by the Resource Owner). Issuing a Refresh Token is optional at the discretion of the Authorization Server. If the Authorization Server issues a Refresh Token, then it is included when issuing an Access Token.

Unlike Access Tokens, Refresh Tokens are intended for use only with Authorization Servers and are never sent to Resource Servers.

There are two options - Client Credential Flow and Authorized User Flow.

Option #1 - Authorization (Client Credential Flow)

For the client_credentials flow - add offline_access scope to the regular token request.

Example request/response:

POST [Endpoint]/token?client_id=[Client_ID]&client_secret=[Client_Secret]&scope=openid%20offline_access&grant_type=client_credentials   HTTP/1.1
Host: privohub-int.privo.com
Content-Type: application/json

...

HTTP/1.1 200 OK
{
"access_token": "eyJraWQiOiJyc2ExIiw...wqU5RaTddjD2QlTgptP_g",
"token_type": "Bearer",
"expires_in": 599,
"refresh_token": "eyJhbGciOiJub25...OTFkNy02MzA4MjU2OGEyNTkifQ",
"scope": "openid offline_access"
}

Exchange your refresh token to access_token at any time accessing PRIVO /token API endpoint. All you need is just your client credentials, specify grant_type = refresh_token and provide refresh_token itself:

Example request/response:

POST [Endpoint]/token?client_id=[Client_ID]&client_secret=[Client_Secret]&grant_type=refresh_token&
refresh_token=eyJhbGciOiJub25lIn0.eyJleH...LTVlYTcwMjI2OWIyYyJ9.   HTTP/1.1
Host: privohub-int.privo.com
Content-Type: application/x-www-form-urlencoded

...

{
"access_token": "eyJraWQiOiJyc2ExIiw...wqU5RaTddjD2QlTgptP_g",
"token_type": "Bearer",
"expires_in": 599,
"refresh_token": "eyJhbGciOiJub25...OTFkNy02MzA4MjU2OGEyNTkifQ",
"scope": "openid offline_access"
}

Option #2 - Authorization (OIDC Authorization Code Flow)

To issue a refresh token for user authentication instead of the client the restriction will be with ** authorization_code** flow. NOTE: By design in OpenId Implicit flow does not support refresh tokens.

Example below is using the INTEGRATION (INT) environment

First, redirect the user to the authentication page:

https://privohub-int.privo.com/authorize?client_id=[Client_ID]&response_mode=query&mode=NORMAL&response_type=code&
scope=TRUST%20openid%20profile%20user_profile%20additional_info%20offline_access&redirect_uri=[Encoded_Redirect_URI]

Authorization page can be customized by providing additional request parameters for example: mode - may be SIMPLE, NORMAL, ADVANCED state - any random characters you want. It will be returned back to your redirect_uri

Since offline_access isn't considered as a standard OpenId scope, once signed in user will be prompted to approve scope claims (or PRIVO can white list such scopes) and when user clicks Authorize button they will be redirected to the defined redirect_uri with authorization code as a request parameter (see example below).

Example

Browser URL: https://www.someredirecturi.com/?code=kfec84

Second, exchange the authorization code for access and refresh tokens - Notice grant_type=authorization_code:

POST [Endpoint]/token?client_id=[Client_ID]&client_secret=[Client_Secret]&redirect_uri=[Encoded_Redirect_URI]&
grant_type=authorization_code&code=kfec84   HTTP/1.1
Host: privohub-int.privo.com
Content-Type: application/json

...

{
"access_token": "eyJraWQiOiJyc2ExIiw...4Ikwt-HFwWr_W6H6qICA",
"token_type": "Bearer",
"expires_in": 599,
"refresh_token": "eyJhbGciOiJub25lI...WMtODU3OS01YzExYjYyZDQxMDYifQ.",
"scope": "user_profile additional_info openid offline_access profile",
"id_token": "eyJraWQiOiJyc2ExIiw...1JGZOpP3eQf1VqC9K9o7uE"
}

Response will contain an access_token that can be used immediately and a refresh_token that can be exchanged at any time (follow Option#1 example above by calling /token). NOTE: By default refresh token never expires.

Expired Token Error Response:

{
        "error": "invalid_token",
        "error_description": "Invalid access token: eyJhbGciOiJSUzIi...3gZthv7Y"
}