Refresh a Token

Use this API to refresh the session for a user and generate a new set of access tokens.

The authentication requirements for this request are dependent on the Token Endpoint Authentication Method that is defined on an OpenId Connect application.

  • Basic - Client ID and Client Secret are required in the Authorization header.
  • POST - Client ID and Client Secret are required in the request body.
  • None (PKCE) - Client ID is required in the request body. Do not include Client Secret. Sending credentials in both Authorization header and payload body will cause an error.

Resource URL

https://<subdomain>.onelogin.com/oidc/2/token

Header Parameter

Authorization

string

Required if Token Endpoint Authentication Method is set to Basic

Set to Basic <base64 encoded "clientId:clientSecret">.

The client_id and client_secret are generated when you configure your OpenId Connect app in OneLogin.

e.g. Using Node.js this would be

new Buffer(`${this.client_id}:${this.client_secret}`).toString('base64');

Content-Type

required

string

application/x-www-form-urlencoded

Resource Parameter

subdomain

required

string

Set to the subdomain of your OneLogin instance.

e.g. oidc-sample where the instance is https://oidc-sample.onelogin.com

Request Parameter

grant_type

required

string

Set to "refresh_token"

refresh_token

required

string

Set this to the refresh_token that was returned via the Create a Session with Username/Password or Authorization Code grants.

client_id

string

The OneLogin generated Client ID for your OpenID Connect app.

Required if Token Endpoint Authentication method is set to POST or none (PKCE).

client_secret

string

The OneLogin generated Client Secret for your OpenID Connect app.

Required if Token Endpoint Authentication method is set to POST.

Sample Request Body

refresh_token=xxxxx&grant_type=refresh_token

Sample Response

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized
{
    "access_token": "ZTUxMWY5OGUtMGRlYi00ZTNkLThjYWEtYzkzY2U4NDVmMmM5gt4dEytSyyNvsA4wragMwLMTa...",
    "expires_in": 3600,
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkpSY080bnhzNWpnYzhZZE43STJoTE80V...",
    "refresh_token": "ZWM0MTI1NzktNjE1My00OTRkLWE2OWMtMWFmOGRlNzA1ZDQ2LqQ6dEuxfqsf9....",
    "token_type": "Bearer"
}

Probably an invalid client_id

{
    "error": "invalid_request",
    "error_description": "Resource not found"
}

The grant_type MUST be set to refresh_token

{
    "error": "unsupported_grant_type",
    "error_description": "unsupported grant_type requested (xxxx)"
}

The authorization header is invalid

{
    "error": "invalid_request",
    "error_description": "invalid authorization header value format"
}
{
    "error": "invalid_request",
    "error_description": "Authentication Failed"
}
{
    "error": "invalid_request",
    "error_description": "User is locked. Access is unauthorized"
}
{
    "error": "invalid_request",
    "error_description": "User is suspended. Access is unauthorized"
}
{
    "error": "invalid_request",
    "error_description": "Access is unauthorized"
}

Response Elements

access_tokenThe token that represents the session that has just been created for the user.
expires_inThe number of seconds until the session expires
id_tokenA JWT containing user and scope information for this session
refresh_tokenThe token that should be used to refresh the session again
token_typeThe type of access token. Always set to "Bearer"

Sample Code

cURL

Replace sample values indicated by < > with your actual values.

curl -XPOST "https://<subdomain>.onelogin.com/oidc/2/token" \
-H "Authorization: Basic <base64 encoded client_id:client_secret>" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token&refresh_token=<refresh token>"

Postman Collection

Run In Postman