OAuth2 Refreshing the token

New OAuth2 access tokens have expirations. Token-expiration periods vary in length, based on how the token was acquired. Tokens return an expires_in field indicating how long the token should last. However, you should build your applications in such a way that they are resilient to token authentication failures. In other words, an application capable of refreshing tokens should not need to know how long a token will live. Rather, it should be prepared to deal with the token becoming invalid at any time.

To allow for applications to remain authenticated for long periods in a world of expiring tokens, we allow for sessions to be refreshed, in accordance with the guidelines in “Refreshing an Access Token” in the OAuth2 RFC. Generally, refresh tokens are used to extend the lifetime of a given authorization.

How to refresh

To refresh a token, you need a refresh token coming from a body. For example

{
  "access_token": "17ebb971-f558-48f2-81b1-788ea927c509",
  "refresh_token": "c6f30bc4-9a04-4e66-a1a1-080fad703a9e",
  "expires_in": 3600,
  "token_type": "bearer"
}

You also need the client_id and client_secret used to generate the above refresh token. To refresh, use this request:

POST https://pulsoid.net/oauth2/token
    --data-urlencode
    ?grant_type=refresh_token
    &refresh_token=<your refresh token>
    &client_id=<your client ID>
    &client_secret=<your client secret>

Parameters explained:

NameTypeDescription

client_id

string

Your client ID.

grant_type

string

Should be refresh_token.

client_secret

string

Your client secret.

refresh_token

string

Refresh token issued to the client.

Example:

POST https://pulsoid.net/oauth2/token
    --data-urlencode
    ?grant_type=refresh_token
    &refresh_token=c6f30bc4-9a04-4e66-a1a1-080fad703a9e
    &client_id=3d3fa070-8358-4984-ae32-94392185df63
    &client_secret=a8262283-f568-4ec3-be84-1c4758dc1a82

Here is a sample response on success. It contains the new access token, refresh token, and scopes associated with the new grant. Your application should then update its record of the refresh token to be the value provided in this response, as the refresh token may change between requests.

{
  "access_token": "79f4bbad-8894-4a04-9e4c-e36bfa0a9867",
  "refresh_token": "9ae58a4b-651a-41c1-a0fe-d3a50920da9b>",
  "expires_in": 3600,
  "token_type": "bearer"
}

After refreshing the old refresh token and access token are invalid. When a user disconnects an app, we delete all tokens for that user. Both refresh and access tokens for that user will return 401 Unauthorized. We recommend performing a refresh when you receive a 401 Unauthorized.

How To Validate Authorization Token?

Last updated