Refresh token

Overview

Exchanges a refresh token for a new access token and a new refresh token. Call it once the access token expires — access tokens last 1 day, refresh tokens last 30 days.

The old refresh token is consumed the moment this succeeds, so persist the new pair immediately. Reusing a spent refresh token returns 400 invalid_grant.

Prerequisites

• No bearer token. This endpoint authenticates with your OAuth client credentials, sent in the request body.

Base URL

Endpoint

POST /oauth/token

Authentication

• No bearer token. Authenticate with your OAuth client credentials in the request body.

Send no Authorization header. The request authenticates with your client_id and client_secret plus the refresh token itself.

Rate limit

• Shares the POST /oauth/token route, which carries the framework's default throttle (60 requests/min per client).

Request body

Send the body as application/x-www-form-urlencoded.

Send as application/x-www-form-urlencoded.

How it works

• 200 returns a new access_token, refresh_token, token_type and expires_in.
• 400 invalid_grant when the refresh token is expired, already used, or does not match the client.
• 401 invalid_client when the client credentials are wrong.
• Once the refresh token passes its 30-day life, the user must sign in again with the password grant.

Response

200 Success · 200

{
  "token_type": "Bearer",
  "expires_in": 86400,
  "access_token": "<new-access-token>",
  "refresh_token": "<new-refresh-token>"
}

400 Invalid refresh token · 400

{
  "error": "invalid_grant",
  "error_description": "The refresh token is invalid."
}

Errors

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/oauth/token" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token={{refreshToken}}' \
  --data-urlencode 'client_id={{oauthClientId}}' \
  --data-urlencode 'client_secret={{oauthClientSecret}}' \
  --data-urlencode 'scope=*'