Skip to content

Refresh Tokens#

Use a refresh token to get a new access token when the old one expires.

Overview#

Your Confidential Client can retrieve a new access token (and refresh token) using the same sort of POST it used in the original OAuth process.

Note grant_type and refresh_token

This is like the POST request in the last step of the OAuth process, but here the grant_type is refresh_token and you provide a refresh_token field instead of an access_token field.

Request#

curl -X POST \
     --data-urlencode "client_id=$CLIENTID" \
     --data-urlencode "client_secret=$CLIENTSECRET" \
     --data-urlencode "refresh_token=$REFRESH" \
     --data-urlencode "grant_type=refresh_token" \
     https://auth.august.com/access_token \
     --trace-ascii /dev/stdout

Response#

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpbnN0YWxsSWQiOiIiLCJyZWdpb24iOiJpcmVsYW5kLXByb2QtYXdzIiwiYXBwbGljYXRpb25JZCI6IiIsInVzZXJJZCI6IjU0YzUzNmYzLTFjNTEtNGVhOC1iODIwLWFlODk3YTY2ZTg0ZSIsInZJbnN0YWxsSWQiOmZhbHNlLCJ2UaFzc3dvcmQiOnRydWUsInZFbWFpbCI6dHJ1ZSwidlBob25lIjp0cnVlLCJoYXNJbnN0YWxsSWQiOmZhbHNlLCJoYXNQYXNzd29yZCI6ZmFsc2UsImhhc0VtYWlsIjpmYWxzZSwiaGFzUGhvbmUiOmZhbHNlLCJpc0xvY2tlZE91dCI6ZmFsc2UsIm9hdXRoIjp7ImFwcF9uYW1lIjoiWmlsbG93IChTdGFnaW5nKSIsImNsaWVudF9pZCI6ImZmOGI4NWExLTU5NTEtNGRjYy04MDJiLTE4NmE5MTliODM2NSIsImFwadtleSI6Ijg2ODUzMmJhLWU0YzgtNDVjZS1hMDVmLTNmNjQzYTYwNjkwNiIsInJlZGlyZWN0X3VyaSI6Imh0dHBzOi8vdHR2MDc0Y3U2ZC5leGVjdXRlLWFwaS51cy13ZXN0LTIuYW1hem9uYXdzLmNvbS9kZXYvYXV0aC9jYWxsYmFjayJ9LCJjYXB0Y2hhIjoiIiwiZW1haWwiOltdLCJwaG9uZSI6W10sImV4cGlyZXNBcCI6IjIwMjEtMTEtMjVUMjM6MDE6MzcuNjE1WiIsInRlbXBvcmFyeUFjY291bnRDcmVhdGlvblBhc3N3b3JkTGluayI6IiIsImlhdCI6MTYyNzUxMzI5NywiZXhwIjoxNjM3ODgxMjk3fQ.hWTjkU7huN_ssT5VloBO3UnxNbGBeWnaTAEbLQ6NLxU",
    "expires_in": 10367999,
    "refresh_token": "00f491c3ea3b043c590fbd0a7594fa47:812cc75d0e6238d261677481d7f9b4b0c00a16947635280bd24e3e4424390ca8"
}

Note about the new refresh_token

Each refresh_token is valid only once. When you request a grant_type=refresh_token, the response provides a new refresh_token which replaces your previous refresh token.

Refresh Token Expiration#

The August refresh_token expires one year after we issue it or as soon as you use it. That is, the refresh_token is only valid once and must be used within a year. Be sure to store the new refresh_token which came back in the response!

If you try to use an expired refresh token, you will receive an HTTP 400 error and an error message in the body of the response, following the OAuth2 specification.

August-Specific Access Token Renewal#

August returns an updated x-august-access-token in the response header to every successful request you make. By using the most recent x-august-access-token, you should always have a valid token -- each new token will extend the valid time a little bit. In the event of your token being invalid, August will return a 401 error and your user will need to OAuth again.

Important

New access tokens do not invalidate previous access tokens.

FAQ#

❔ Can I reuse my refresh_token?#

  • No, each refresh_token is valid only once. In the response you will receive a new refresh_token.

❔ How long do August refresh tokens last?#

  • Refresh tokens expire after one year, or when they are used or revoked. A refresh token may be redeemed one time.

❔ How long do August access tokens last?#

  • Please see the expires_in field returned with the access token.
  • We currently set access tokens to last 4 months, but this could change at any time.

❔ How often should I update my cached x-august-access-token?#

  • Life will be simpler if you use the OAuth 2 refresh token (see above).
  • If you can update x-august-access-token on every request, that would be ideal. If you are worried about database access times or other storage issues, then updating once every 24 hours should be sufficient. That is, it is unlikely that we would ever issue access tokens valid for less than 24 hours. So store the date you received the access token with the access token, and when you get a new token in a response, if the old token is more than 24 hours old, replace it with the new token. That way you update your stored token no more than once per day.

❔ How can I verify my new token before replacing my old token?#

  • You could make a quick call to GET /users/me (or any other useful API) using the new token.