Skip to main content
are used to request a new and/or for a user without requiring them to re-authenticate. Typically, you should request a new access token before the previous one expires (to avoid any service interruption), but not every time you call an API, as token exchanges are subject to our Rate Limiting Policy. You may also use a refresh token to request a new ID token for a user, and should do so if you need to refresh the claims within the ID token.

​
Call the API

To exchange the refresh token you received during authentication for a new access token, call the Auth0 Authentication API Get token endpoint in the Authentication API. To learn more about the authentication methods available for the Authentication API, read Authentication Methods.

​
Use Basic authentication

​
Use Post authentication

​
Parameter definition

ParameterDescription
grant_typeType of grant to execute.
client_idApplication’s client ID.
client_secret(Optional) Application’s client secret. Only required for confidential applications using the Post token authentication method.
refresh_tokenRefresh token to exchange.
The response will include a new access token, its type, its lifetime (in seconds), and the granted scopes. If the scope of the initial token included openid, then a new ID token will be in the response as well. 
{
      "access_token": "eyJ...MoQ",
      "expires_in": 86400,
      "scope": "openid offline_access",
      "id_token": "eyJ...0NE",
      "token_type": "Bearer"
    }

​
Bypass MFA

If Multi-factor Authentication (MFA) is enabled and the refresh token exchange flow fails, you can use the below Action code to bypass the logic: 
exports.onExecutePostLogin = async (event, api) => {
  // This action will allow you to bypass the MFA logic for the refresh token exchange flow.

  if (event.transaction.protocol === "oauth2-refresh-token") {
    return;
  }

  //  Add your MFA logic
  //  For example: api.multifactor.enable("any");
};
You can customize the code example when separate logic needs to be executed or bypassed depending on the current flow or protocol.

​
Customize MFA

Customizable MFA with the Resource Owner Password Grant, Embedded, or Refresh Token flows is in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s Master Subscription Agreement. To learn more about Auth0’s release stages, read Product Release Stages. To participate in the early access, contact Auth0 Support.
Customizable MFA allows users to enroll and challenge with factors of their choice that are supported by your application. During authentication at the oauth/token endpoint, the response returns the mfa_required error that includes the mfa_token to use the MFA API and the mfa_requirements parameter with a list of authenticators: 
{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "Fe26...Ha",
  "mfa_requirements": {
    "challenge": [
      { "type": "otp" },
      { "type": "push-notification" },
      { "type": "phone" },
      { "type": "recovery-code" }
      { "type": "email"} //can only work with challenge
    ]
  }
}
Use the mfa_token to call the mfa/authenticator endpoint for a list of all factors the user has enrolled and match the same type your application supports. You also need to obtain the matching authenticator_type to issue challenges: 
[
  {
    "type": "recovery-code",
    "id": "recovery-code|dev_qpOkGUOxBpw6R16t",
    "authenticator_type": "recovery-code",
    "active": true
  },
  {
    "type": "otp",
    "id": "totp|dev_6NWz8awwC8brh2dN",
    "authenticator_type": "otp",
    "active": true
  }
]
Enforce the MFA challenge by calling the request/mfa/challenge endpoint. Further customize your MFA flow with Auth0 Actions. To learn more, read Actions Triggers: post-challenge - API Object.

​
Learn more