Refresh Tokens

A session token (proxy_auth_token) expires after the Session Time you set on your Block. A refresh token lets your app get a new session without making the user sign in again.

Every successful login, sign-up and social login returns a refresh_token alongside the proxy_auth_token. Store it somewhere safe, such as an HTTP-only cookie or your backend.

#

Refresh a session

POST /c/refreshToken

No proxy_auth_token header is needed. The refresh token is the only credential.

Field Required Notes
refresh_token yes The latest refresh_token you received from login, sign-up or a previous refresh. 
curl -X POST https://routes.msg91.com/api/c/refreshToken \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "<your refresh token>"}'

{
  "data": {
    "proxy_auth_token": "<session token>",
    "refresh_token": "<new refresh token>",
    "expires_in": 86400
  },
  "status": "success",
  "hasError": false,
  "errors": []
}
  • If the user's session is still active, the same proxy_auth_token stays valid and its expiry is extended.
  • If the session has already expired, you get a brand-new proxy_auth_token.
  • expires_in is your Block's Session Time, in seconds.
#

Refresh tokens rotate

Every refresh returns a new refresh_token and the old one stops working. Always save the new one.

Presenting a refresh token that has already been used is treated as a sign it may have leaked, and revokes that user's whole refresh chain. The user has to sign in again.

A refresh token also has a maximum lifetime, set on your Block. Once it passes, the user has to sign in again.

#

Errors

Status Message What to do
401 Invalid or expired refresh token. Please log in again. The token is unknown, expired or already used. Send the user to the login page.
429 Refresh already in progress, please retry. Two requests used the same token at once. Wait a moment and retry with the latest token.
429 Too many refresh attempts. Please try again shortly. You are limited to 10 refresh calls per minute per IP address.
422 Validation error refresh_token is missing.
#

Ending the session

Calling DELETE /c/logout, or resetting the user's password, revokes the user's refresh tokens as well as their session. See Companies.

Built with DocStar