Introduction

The Authentication API enables you to manage all aspects of user identity when you use Auth0. It offers endpoints so your users can log in, sign up, log out, access APIs, and more.

The API supports various identity protocols, like OpenID Connect, OAuth 2.0, and SAML.

The Authentication API is served over HTTPS. All URLs referenced in the documentation have the following base: https://{yourDomain}

You have five options for authenticating with this API:

• OAuth2 Access Token
• Client ID and Client Assertion (confidential applications)
• Client ID and Client Secret (confidential applications)
• Client ID (public applications)
• mTLS Authentication (confidential applications)

Send a valid Access Token in the Authorization header, using the Bearer authentication scheme.

An example is the Get User Info endpoint. In this scenario, you get an Access Token when you authenticate a user, and then you can make a request to the Get User Info endpoint, using that token in the Authorization header, in order to retrieve the user's profile.

Generate a client assertion containing a signed JSON Web Token (JWT) to authenticate. In the body of the request, include your Client ID, a client_assertion_type parameter with the value urn:ietf:params:oauth:client-assertion-type:jwt-bearer, and a client_assertion parameter with your signed assertion. Review Private Key JWT for examples.

Send the Client ID and Client Secret. The method you can use to send this data is determined by the Token Endpoint Authentication Method configured for your application.

If you are using Post, you must send this data in the JSON body of your request.

If you are using Basic, you must send this data in the Authorization header, using the Basic authentication scheme. To generate your credential value, concatenate your Client ID and Client Secret, separated by a colon (:), and encode it in Base64.

An example is the Revoke Refresh Token endpoint. This option is available only for confidential applications (such as applications that are able to hold credentials in a secure way without exposing them to unauthorized parties).

Send the Client ID. For public applications (applications that cannot hold credentials securely, such as SPAs or mobile apps), we offer some endpoints that can be accessed using only the Client ID.

An example is the Implicit Grant.

Generate a certificate, either self-signed or certificate authority signed. Then, set up the customer edge network that performs the mTLS handshake.

Once your edge network verifies the certificate, forward the request to the Auth0 edge network with the following headers:

• The Custom Domain API key as the cname-api-key header.
• The client certificate as the client-certificate header.
• The client certificate CA verification status as the client-certificate-ca-verified header. For more information, see Forward the Request.

To learn more, read Authenticate with mTLS.

For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

GET https://{yourDomain}/some-endpoint?param=value&param=value

For POST requests, parameters not included in the URL should be encoded as JSON with a Content-Type of application/json:

curl --request POST --url 'https://{yourDomain}/some-endpoint' --header 'content-type: application/json' --data '{"param": "value", "param": "value"}'

For each endpoint, you will find sample snippets you can use, in three available formats:

• HTTP request
• Curl command
• JavaScript: depending on the endpoint each snippet may use the Auth0.js library, Node.js code or simple JavaScript

Each request should be sent with a Content-Type of application/json.

You can test the endpoints using the Authentication API Debugger.

The Authentication API Debugger is an Auth0 extension you can use to test several endpoints of the Authentication API.

If it's the first time you use it, you have to install it using the dashboard. Once you do, you are ready to configure your app's settings and run your tests.

Note that its URL varies according to your tenant's region:

• US West
• Europe Central
• Australia

When an error occurs, you will receive an error object. Most of these error objects contain an error code and an error description so that your applications can more efficiently identify the problem.

If you get an 4xx HTTP response code, then you can assume that there is a bad request from your end. In this case, check the Standard Error Responses for more context.

5xx errors suggest a problem on Auth0's end, so in this case, check Auth0 Status Page and @auth0status on Twitter to see how our systems are doing.

In any other case you can use our support options.

The Authentication API is subject to rate limiting. The limits differ per endpoint.

If you exceed the provided rate limit for a given endpoint, you will receive the 429 Too Many Requests response with the following message: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.

For details on rate limiting, refer to Auth0 API Rate Limit Policy.

Note that for database connections Auth0 limits certain types of repeat login attempts depending on the user account and IP address. For details, refer to Rate Limits on User/Password Authentication.

If you have problems or need help with your case, you can always reach out to our Support.

Note that if you have a free subscription plan, and you are not in your 22-day trial period, you will not be able to access or open tickets in the Support Center. In this case, you can seek support through the Auth0 Community. For more info on our support program, refer to Support Options.

Login

GET https://{yourDomain}/authorize?
  response_type=code|token&
  client_id={yourClientId}&
  connection=CONNECTION&
  redirect_uri={https://yourApp/callback}&
  state=STATE&
  ADDITIONAL_PARAMETERS

// Script uses auth0.js. See Remarks for details.
<script src="https://cdn.auth0.com/js/auth0/9.11/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize app
  var webAuth = new auth0.WebAuth({
    domain:       '{yourDomain}',
    clientID:     '{yourClientId}'
  });

  // Trigger login with google
  webAuth.authorize({
    connection: 'google-oauth2'
  });

  // Trigger login with github
  webAuth.authorize({
    connection: 'github'
  });

  // Trigger login popup with twitter
  webAuth.popup.authorize({
    connection: 'twitter'
  });
</script>

Use this endpoint to authenticate a user with a social provider. It will return a 302 redirect to the social provider specified in connection.

1. At the Configuration tab, set the fields Application (select the application you want to use for the test) and Connection (the name of the social connection to use).

2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.

3. At the OAuth2 / OIDC tab, click OAuth2 / OIDC Login.

• The redirect_uri value must be specified as a valid callback URL under your Application's Settings.

• If response_type=token, after the user authenticates on the provider, it will redirect to your application callback URL passing the Access Token and ID Token in the address location.hash. This is used for Single-Page Apps and also on Native Mobile SDKs.

• The sample auth0.js script uses the library version 8. If you are using auth0.js version 7, please see this reference guide.

• Supported Social Identity Providers
• Custom Social Connections
• State Parameter
• Auth0.js /authorize Method Reference

GET https://{yourDomain}/authorize?
  response_type=code|token&
  client_id={yourClientId}&
  connection=CONNECTION&
  redirect_uri={https://yourApp/callback}&
  scope=openid%20profile%20email&
  state=STATE

// Script uses auth0.js. See Remarks for details.
<script src="https://cdn.auth0.com/js/auth0/9.11/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize app
  var webAuth = new auth0.WebAuth({
    domain:       '{yourDomain}',
    clientID:     '{yourClientId}'
  });

  // Calculate URL to redirect to
  var url = webAuth.client.buildAuthorizeUrl({
    clientID: '{yourClientId}', // string
    responseType: 'token', // code or token
    redirectUri: '{https://yourApp/callback}',
    scope: 'openid profile email'
    state: 'YOUR_STATE'
  });

  // Redirect to url
  // ...
</script>

Use this endpoint for browser based (passive) authentication. It returns a 302 redirect to the Auth0 Login Page that will show the Login Widget where the user can log in with email and password.

1. At the Configuration tab, set the fields Application (select the application you want to use for the test) and Connection (the name of the social connection to use).

2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.

3. At the OAuth2 / OIDC tab, click OAuth2 / OIDC Login.

• The redirect_uri value must be specified as a valid callback URL under your Application's Settings.
• If response_type=token, after the user authenticates, it will redirect to your application callback URL passing the Access Token and ID Token in the address location.hash. This is used for Single-Page Apps and also on Native Mobile SDKs.
• The main difference between passive and active authentication is that the former happens in the browser through the Auth0 Login Page and the latter can be invoked from anywhere (a script, server to server, and so forth).
• The sample auth0.js script uses the library version 8. If you are using auth0.js version 7, please see this reference guide.

• Database Identity Providers
• Rate Limits on User/Password Authentication
• Active Directory/LDAP Connector
• State Parameter
• Auth0.js /authorize Method Reference

GET https://{yourDomain}/authorize?
  response_type=code|token&
  client_id={yourClientId}&
  connection=CONNECTION&
  redirect_uri={https://yourApp/callback}&
  state=STATE

// Script uses auth0.js. See Remarks for details.
<script src="https://cdn.auth0.com/js/auth0/9.11/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize application
  var webAuth = new auth0.WebAuth({
    domain:       '{yourDomain}',
    clientID:     '{yourClientId}'
  });

  // Calculate URL to redirect to
  var url = webAuth.client.buildAuthorizeUrl({
    clientID: 'YOUR_CLIENT_ID', // string
    responseType: 'token', // code or token
    redirectUri: 'https://YOUR_APP/callback',
    scope: 'openid profile email'
    state: 'YOUR_STATE'
  });

  // Redirect to url
  // ...
</script>

Use this endpoint for passive authentication. It returns a 302 redirect to the SAML Provider (or Windows Azure AD and the rest, as specified in the connection) to enter their credentials.

1. At the Configuration tab, set the fields Application (select the application you want to use for the test) and Connection (the name of the social connection to use).

2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.

3. At the OAuth2 / OIDC tab, click OAuth2 / OIDC Login.

• If no connection is specified, it will redirect to the Login Page and show the Login Widget.
• The redirect_uri value must be specified as a valid callback URL under your Application's Settings.
• If response_type=token, after the user authenticates, it will redirect to your application callback URL passing the Access Token and ID Token in the address location.hash. This is used for Single-Page Apps and also on Native Mobile SDKs.
• Additional parameters can be sent that will be passed to the provider.
• The sample auth0.js script uses the library version 8. If you are using auth0.js version 7, please see this reference guide.

• SAML
• Obtain a Client Id and Client Secret for Microsoft Azure Active Directory
• State Parameter
• Auth0.js /authorize Method Reference

Logout

GET https://{yourDomain}/v2/logout?
  client_id={yourClientId}&
  returnTo=LOGOUT_URL

curl --request GET \
  --url 'https://{yourDomain}/v2/logout' \
  --header 'content-type: application/json' \
  --data '{"client_id":"{yourClientId}", "returnTo":"LOGOUT_URL"}'

// Script uses auth0.js. See Remarks for details.
<script src="https://cdn.auth0.com/js/auth0/9.11/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize application
  var webAuth = new auth0.WebAuth({
    domain:       '{yourDomain}',
    clientID:     '{yourClientId}'
  });
  
  webAuth.logout({
    returnTo: 'YOUR_LOGOUT_URL',
    client_id: '{yourClientId}'
  });
</script>

Use this endpoint to logout a user. If you want to navigate the user to a specific URL after the logout, set that URL at the returnTo parameter. The URL should be included in any the appropriate Allowed Logout URLs list:

• If the client_id parameter is included, the returnTo URL must be listed in the Allowed Logout URLs set at the application level (see Setting Allowed Logout URLs at the App Level).
• If the client_id parameter is NOT included, the returnTo URL must be listed in the Allowed Logout URLs set at the tenant level (see Setting Allowed Logout URLs at the Tenant Level).
• If the client_id parameter is included and the returnTo URL is NOT set, the server returns the user to the first Allowed Logout URLs set in the Dashboard (see Setting Allowed Logout URLs at the Tenant Level).

1. At the Configuration tab, set the fields Application (select the application you want to use for the test) and Connection (the name of the social connection to use).

2. Copy the Callback URL and set it as part of the Allowed Logout URLs of your Application Settings.

3. At the Other Flows tab, click Logout, or Logout (Federated) to log the user out of the identity provider as well.

• Logging the user out of their identity provider is not common practice, so think about the user experience before you use the federated query string parameter.
• The sample auth0.js script uses the library version 8. If you are using auth0.js version 7, please see this reference guide.

• Logout

GET https://{yourDomain}/oidc/logout?
  post_logout_redirect_uri=LOGOUT_URL&
  id_token_hint=ID_TOKEN_HINT

curl --request GET \
  --url 'https://{yourDomain}/oidc/logout' \
  --header 'content-type: application/json' \
  --data-raw '
  { 
    "client_id":"{yourClientId}", 
    "post_logout_redirect_uri":"LOGOUT_URL", 
    "id_token_hint":"ID_TOKEN_HINT"
  }'

// Script uses auth0.js. See Remarks for details.
<script src="https://cdn.auth0.com/js/auth0/9.11/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize application
  var webAuth = new auth0.WebAuth({
    domain:       '{yourDomain}',
    clientID:     '{yourClientId}'
  });
  
  webAuth.logout({
    post_logout_redirect_uri: 'YOUR_LOGOUT_URL',
    id_token_hint: 'YOUR_ID_TOKEN_HINT'
  });
</script>

Use this endpoint to logout a user. If you want to navigate the user to a specific URL after the logout, set that URL at the post_logout_redirect_uri parameter. The URL should be included in the appropriate Allowed Logout URLs list:

• If the id_token_hint parameter is included:
  • When the client_id parameter is included, the server uses the URL from the aud claim in the id_token_hint to select which of the Allowed Logout URLs to use from the application specified by the client_id.
  • When the client_id parameter is NOT included, the server uses the URL from the aud claim in the id_token_hint to select which of the Allowed Logout URLs at the tenant level to use.
• If the id_token_hint parameter is not included:
  • If the client_id parameter is included, the post_logout_redirect_uri URL must be listed in the Allowed Logout URLs set at the application level (see Setting Allowed Logout URLs at the App Level).
  • If the client_id parameter is NOT included, the post_logout_redirect_uri URL must be listed in the Allowed Logout URLs set at the tenant level (see Setting Allowed Logout URLs at the Tenant Level).
  • If the client_id parameter is included and the post_logout_redirect_uri URL is NOT set, the server returns the user to the first Allowed Logout URLs set in the Dashboard (see Setting Allowed Logout URLs at the Tenant Level).

1. At the Configuration tab, set the fields Application (select the application you want to use for the test) and Connection (the name of the social connection to use).

2. Copy the Callback URL and set it as part of the Allowed Logout URLs of your Application Settings.

3. At the Other Flows tab, click Logout, or Logout (Federated) to log the user out of the identity provider as well.

• Logging the user out of their social identity provider is not common practice, so think about the user experience before you use the federated query string parameter with social identity providers.
• If providing both id_token_hint and logout_hint, the logout_hint value must match the sid claim from the id_token_hint.
• If providing both id_token_hint and client_id, the client_id value must match the aud claim from the id_token_hint.
• If id_token_hint is not provided, then the user will be prompted for consent unless a logout_hint that matches the user's session ID is provided.
• The POST HTTP method is also supported for this request. When using POST, the request parameters should be provided in the request body as form parameters instead of the query string. The federated parameter requires a value of true or false.
• This conforms to the OIDC RP-initiated Logout Specification.

• Logout
• Use the OIDC Endpoint to Log Users Out of Auth0
• OIDC RP-initiated Logout Specification

POST https://{yourDomain}/samlp/CLIENT_ID/logout

curl --request POST \
  --url 'https://{yourDomain}/samlp/CLIENT_ID/logout' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data '{SAML_LOGOUT_REQUEST}'

Use this endpoint to log out a user from an Auth0 tenant configured as a SAML identity provider (IdP).

Logout behavior is determined by the configuration of the SAML2 Web App addon for the application on the Auth0 tenant acting as the SAML IdP. To learn more, read Log Users Out of SAML Identity Providers.

• The POST body must contain a valid SAML <LogoutRequest> message. To learn more, read Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0 on Oasis.

• Logout
• Log Users Out of SAML Identity Providers

Passwordless

Passwordless connections do not require the user to remember a password. Instead, another mechanism is used to prove identity, such as a one-time code sent through email or SMS, every time the user logs in.

POST https://{yourDomain}/passwordless/start
Content-Type: application/json
{
  "client_id": "{yourClientId}",
  "client_secret": "YOUR_CLIENT_SECRET", // for web applications
  "connection": "email|sms",
  "email": "USER_EMAIL", //set for connection=email
  "phone_number": "USER_PHONE_NUMBER", //set for connection=sms
  "send": "link|code", //if left null defaults to link
  "authParams": { // any authentication parameters that you would like to add
    "scope": "openid",
    "state": "YOUR_STATE"
  }
}

curl --request POST \
  --url 'https://{yourDomain}/passwordless/start' \
  --header 'content-type: application/json' \
  --data '{"client_id":"{yourClientId}", "connection":"email|sms", "email":"USER_EMAIL", "phone_number":"USER_PHONE_NUMBER", "send":"link|code", "authParams":{"scope": "openid","state": "YOUR_STATE"}}'

// Script uses auth0.js. See Remarks for details.
<script src="https://cdn.auth0.com/js/auth0/9.11/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize application
  var webAuth = new auth0.WebAuth({
    domain:       '{yourDomain}',
    clientID:     '{yourClientId}'
  });

  // Send a verification code using email
  webAuth.passwordlessStart({
      connection: 'email',
      send: 'code',
      email: 'USER_EMAIL'
    }, function (err,res) {
      // handle errors or continue
    }
  );

  // Send a link using email
  webAuth.passwordlessStart({
      connection: 'email',
      send: 'link',
      email: 'USER_EMAIL'
    }, function (err,res) {
      // handle errors or continue
    }
  );

  // Send a verification code using SMS
  webAuth.passwordlessStart({
      connection: 'sms',
      send: 'code',
      phoneNumber: 'USER_PHONE_NUMBER'
    }, function (err,res) {
      // handle errors or continue
    }
  );
</script>

You have three options for passwordless authentication:

• Send a verification code using email.
• Send a link using email.
• Send a verification code using SMS.

• If you sent a verification code, using either email or SMS, after you get the code, you have to authenticate the user using the /passwordless/verify endpoint, using email or phone_number as the username, and the verification code as the password.
• This endpoint is designed to be called from the client-side, and is subject to rate limits.
• The sample auth0.js script uses the library version 8. If you are using auth0.js version 7, please see this reference guide.

For the complete error code reference for this endpoint refer to Errors > POST /passwordless/start.

• Passwordless Authentication
• Passwordless Best Practices

POST https://{yourDomain}/oauth/token
Content-Type: application/json
{
  "grant_type" : "http://auth0.com/oauth/grant-type/passwordless/otp",
  "client_id": "{yourClientId}",
  "client_secret": "YOUR_CLIENT_SECRET", // for web applications
  "otp": "CODE",
  "realm": "email|sms" //email or sms
  "username":"USER_EMAIL|USER_PHONE_NUMBER", // depends on which realm you chose
  "audience" : "API_IDENTIFIER", // in case you need an access token for a specific API
  "scope": "SCOPE",
  "redirect_uri": "REDIRECT_URI"
}

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/json' \
  --data '{"grant_type":"http://auth0.com/oauth/grant-type/passwordless/otp", "client_id":"{yourClientId}", "client_secret":"CLIENT_SECRET", "otp":"CODE", "realm":"email|sms", "username":"USER_EMAIL|USER_PHONE_NUMBER", "audience":"API_IDENTIFIER", "scope":"SCOPE", "redirect_uri": "REDIRECT_URI"}'

// Script uses auth0.js. See Remarks for details.
<script src="https://cdn.auth0.com/js/auth0/9.11/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize application
  var webAuth = new auth0.WebAuth({
    domain:       '{yourDomain}',
    clientID:     '{yourClientId}'
  });

  // Verify code sent via email
  webAuth.passwordlessLogin({
      connection: 'email',
      email: 'USER_EMAIL',
      verificationCode: 'VERIFICATION_CODE_SENT'
    }, function (err,res) {
      // handle errors or continue
    }
  );

  // Verify code sent within link using email
  webAuth.passwordlessLogin({
      connection: 'email',
      email: 'USER_EMAIL',
      verificationCode: 'VERIFICATION_CODE_SENT_WITHIN_LINK'
    }, function (err,res) {
      // handle errors or continue
    }
  );

  // Verify code sent via SMS
  webAuth.passwordlessLogin({
      connection: 'sms',
      phoneNumber: 'USER_PHONE_NUMBER',
      verificationCode: 'VERIFICATION_CODE_SENT'
    }, function (err,res) {
      // handle errors or continue
    }
  );
</script>

Once you have a verification code, use this endpoint to login the user with their phone number/email and verification code.

1. At the Configuration tab, set the fields Application (select the application you want to use for the test) and Connection (use sms or email).

2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.

3. At the OAuth2 / OIDC tab, set Username to the user's phone number if connection=sms, or the user's email if connection=email, and Password to the user's verification code. Click Resource Owner Endpoint.

For the complete error code reference for this endpoint refer to Standard Error Responses.

• Passwordless Authentication

Once you have a verification code, use this endpoint to login the user with their phone number/email and verification code. This is active authentication, so the user must enter the code in your app.

1. At the Configuration tab, set the fields Application (select the application you want to use for the test) and Connection (use sms or email).

2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.

3. At the OAuth2 / OIDC tab, set Username to the user's phone number if connection=sms, or the user's email if connection=email, and Password to the user's verification code. Click Resource Owner Endpoint.

• The profile scope value requests access to the End-User's default profile Claims, which are: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at.
• The email scope value requests access to the email and email_verified Claims.
• The sample auth0.js script uses the library version 8. If you are using auth0.js version 7, please see this reference guide.

For the complete error code reference for this endpoint refer to Errors > POST /passwordless/verify.

• Passwordless Best Practices

Signup

POST https://{yourDomain}/dbconnections/signup
Content-Type: application/json
{
  "client_id": "{yourClientId}",
  "email": "EMAIL",
  "password": "PASSWORD",
  "connection": "CONNECTION",
  "username": "johndoe",
  "given_name": "John",
  "family_name": "Doe",
  "name": "John Doe",
  "nickname": "johnny",
  "picture": "http://example.org/jdoe.png"
  "user_metadata": { plan: 'silver', team_id: 'a111' }
}

curl --request POST \
  --url 'https://{yourDomain}/dbconnections/signup' \
  --header 'content-type: application/json' \
  --data '{"client_id":"{yourClientId}", "email":"test.account@signup.com", "password":"PASSWORD", "connection":"CONNECTION", "username": "johndoe", "given_name": "John", "family_name": "Doe", "name": "John Doe", "nickname": "johnny", "picture": "http://example.org/jdoe.png", "user_metadata":{ "plan": "silver", "team_id": "a111" }}'

// Script uses auth0.js. See Remarks for details.
<script src="https://cdn.auth0.com/js/auth0/9.11/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize client
  var webAuth = new auth0.WebAuth({
    domain:       '{yourDomain}',
    clientID:     '{yourClientId}'
  });
  
  webAuth.signup({ 
    connection: 'CONNECTION', 
    email: 'EMAIL', 
    password: 'PASSWORD',
    username: "johndoe",
    given_name: "John",
    family_name: "Doe",
    name: "John Doe",
    nickname: "johnny",
    picture: "http://example.org/jdoe.png",
    user_metadata: { plan: 'silver', team_id: 'a111' }
  }, function (err) { 
    if (err) return alert('Something went wrong: ' + err.message); 
      return alert('success signup without login!') 
  });
</script>

RESPONSE SAMPLE:

{
  "_id": "58457fe6b27...",
  "email_verified": false,
  "email": "test.account@signup.com",
  "username": "johndoe",
  "given_name": "John",
  "family_name": "Doe",
  "name": "John Doe",
  "nickname": "johnny",
  "picture": "http://example.org/jdoe.png"
}

Given a user's credentials, and a connection, this endpoint will create a new user using active authentication.

This endpoint only works for database connections.

• The sample auth0.js script uses the library version 8. If you are using auth0.js version 7, please see this reference guide.

• Password Strength in Auth0 Database Connections
• Password Options in Auth0 Database Connections
• Adding Username for Database Connections
• Metadata Overview

Change Password

POST https://{yourDomain}/dbconnections/change_password
Content-Type: application/json
{
  "client_id": "{yourClientId}",
  "email": "EMAIL",
  "connection": "CONNECTION",
  "organization": "ORGANIZATION_ID"
}

curl --request POST \
  --url https://{yourDomain}/dbconnections/change_password \
  --header 'content-type: application/json' \
  --data '{"client_id": "{yourClientId}","email": "EMAIL", "connection": "CONNECTION", "organization": "ORGANIZATION_ID"}'

// Script uses auth0.js. See Remarks for details.
<script src="https://cdn.auth0.com/js/auth0/9.11/auth0.min.js"></script>
<script type="text/javascript">
  var webAuth = new auth0.WebAuth({
    domain:       '{yourDomain}',
    clientID:     '{yourClientId}'
  });
  
  webAuth.changePassword({
    connection: 'CONNECTION',
    email:   'EMAIL',
    organization: 'ORGANIZATION_ID'
  }, function (err, resp) {
    if(err){
      console.log(err.message);
    }else{
      console.log(resp);
    }
  });
</script>

RESPONSE SAMPLE:

"We've just sent you an email to reset your password."

Send a change password email to the user's provided email address and connection.

Optionally, you may provide an Organization ID to support Organization-specific variables in customized email templates and to include the organization_id and organization_name parameters in the Redirect To URL.

Note: This endpoint only works for database connections.

• When the user clicks on the password change link they will be redirected to a page asking them for a new password.
• This endpoint will return three HTTP Response Headers, that provide relevant data on its rate limits:
  • X-RateLimit-Limit: Number of requests allowed per minute.
  • X-RateLimit-Remaining: Number of requests available. Each new request reduces this number by 1. For each minute that passes, requests are added back, so this number increases by 1 each time.
  • X-RateLimit-Reset: Remaining time until the rate limit (X-RateLimit-Limit) resets. The value is in UTC epoch seconds.

• Changing a User's Password
• Password Strength in Auth0 Database Connections
• Password Options in Auth0 Database Connections
• Auth0 API Rate Limit Policy

User Profile

GET https://{yourDomain}/userinfo
Authorization: 'Bearer {ACCESS_TOKEN}'

curl --request GET \
  --url 'https://{yourDomain}/userinfo' \
  --header 'Authorization: Bearer {ACCESS_TOKEN}' \
  --header 'Content-Type: application/json'

// Script uses auth0.js. See Remarks for details.
<script src="https://cdn.auth0.com/js/auth0/9.11/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize the Auth0 application
  var webAuth = new auth0.WebAuth({
    domain:       '{yourDomain}',
    clientID:     '{yourClientId}'
  });

  // Parse the URL and extract the Access Token
  webAuth.parseHash(window.location.hash, function(err, authResult) {
    if (err) {
      return console.log(err);
    }
    webAuth.client.userInfo(authResult.accessToken, function(err, user) {
        // This method will make a request to the /userinfo endpoint
        // and return the user object, which contains the user's information,
        // similar to the response below.
    });
  });
</script>

RESPONSE SAMPLE:

{
  "sub": "248289761001",
  "name": "Jane Josephine Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "middle_name": "Josephine",
  "nickname": "JJ",
  "preferred_username": "j.doe",
  "profile": "http://exampleco.com/janedoe",
  "picture": "http://exampleco.com/janedoe/me.jpg",
  "website": "http://exampleco.com",
  "email": "janedoe@exampleco.com",
  "email_verified": true,
  "gender": "female",
  "birthdate": "1972-03-31",
  "zoneinfo": "America/Los_Angeles",
  "locale": "en-US",
  "phone_number": "+1 (111) 222-3434",
  "phone_number_verified": false,
  "address": {
    "country": "us"
  },
  "updated_at": "1556845729"
}

Given the Auth0 Access Token obtained during login, this endpoint returns a user's profile.

This endpoint will work only if openid was granted as a scope for the Access Token. The user profile information included in the response depends on the scopes requested. For example, a scope of just openid may return less information than a a scope of openid profile email.

• The sample auth0.js script uses the library version 8. If you are using auth0.js version 7, please see this reference guide.
• The auth0.js parseHash method, requires that your tokens are signed with RS256, rather than HS256.
• To return user_metadata or other custom information from this endpoint, add a custom claim to the ID token with an Action. For more information refer to User profile claims and scope.
• This endpoint will return three HTTP Response Headers, that provide relevant data on its rate limits:
  • X-RateLimit-Limit: Number of requests allowed per minute.
  • X-RateLimit-Remaining: Number of requests available. Each new request reduces this number by 1. For each minute that passes, requests are added back, so this number increases by 1 each time.
  • X-RateLimit-Reset: Remaining time until the rate limit (X-RateLimit-Limit) resets. The value is in UTC epoch seconds.
• The Email claim returns a snapshot of the email at the time of login
• Standard claims (other than email) return the latest value (unless the value comes from an external IdP)
• Custom claims always returns the latest value of the claim
• To access the most up-to-date values for the email or custom claims, you must get new tokens. You can log in using silent authentication (where the prompt parameter for your call to the authorize endpoint equals none)
• To access the most up-to-date values for standard claims that were changed using an external IdP (for example, the user changed their email address in Facebook)., you must get new tokens. Log in again using the external IdP, but not with silent authentication.

• Auth0.js v8 Reference: Extract the authResult and get user info

• Auth0 API Rate Limit Policy

Multi-factor Authentication

The Multi-factor Authentication (MFA) API endpoints allow you to enforce MFA when users interact with the Token endpoints, as well as enroll and manage user authenticators.

First, request a challenge based on the challenge types supported by the application and user. If you know that one-time password (OTP) is supported, you can skip the challenge request.

Next, verify the multi-factor authentication using the /oauth/token endpoint and the specified challenge type: a one-time password (OTP), a recovery code, or an out-of-band (OOB) challenge.

For more information, check out:

• Multi-factor Authentication and Resource Owner Password
• Multi-factor Authentication API
• Multi-factor Authentication in Auth0

POST https://{yourDomain}/mfa/challenge
Content-Type: application/json
{
  "client_id": "{yourClientId}",
  "client_secret": "YOUR_CLIENT_SECRET",
  "mfa_token": "MFA_TOKEN",
  "challenge_type": "oob|otp"
}

curl --request POST \
  --url 'https://{yourDomain}/mfa/challenge' \
  --header 'content-type: application/json' \
  --data '{"mfa_token":"MFA_TOKEN", "challenge_type":"oob otp", "client_id": "{yourClientId}", "client_secret": "YOUR_CLIENT_SECRET"}'

var request = require("request");

var options = { method: 'POST',
  url: 'https://{yourDomain}/mfa/challenge',
  headers: { 'content-type': 'application/json' },
  body:
   { mfa_token: 'MFA_TOKEN',
     challenge_type: 'oob otp',
     client_id: '{yourClientId}',
     client_secret: 'YOUR_CLIENT_SECRET' },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

RESPONSE SAMPLE FOR OTP:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "challenge_type":"otp",
}

RESPONSE SAMPLE FOR OOB WITHOUT BINDING METHOD:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "challenge_type":"oob",
  "oob_code": "abcde...dasg"
}

RESPONSE SAMPLE FOR OOB WITH BINDING METHOD:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "challenge_type":"oob",
  "binding_method":"prompt",
  "oob_code": "abcde...dasg"
}

Request a challenge for multi-factor authentication (MFA) based on the challenge types supported by the application and user.

The challenge_type is how the user will get the challenge and prove possession. Supported challenge types include:

• otp: for one-time password (OTP)
• oob: for SMS/Voice messages or out-of-band (OOB)

If OTP is supported by the user and you don't want to request a different factor, you can skip the challenge request and verify the multi-factor authentication with a one-time password.

• This endpoint does not support enrollment; the user must be enrolled with the preferred method before requesting a challenge.
• Auth0 chooses the challenge type based on the application's supported types and types the user is enrolled with.
• An unsupported_challenge_type error is returned if your application does not support any of the challenge types the user has enrolled with.
• An unsupported_challenge_type error is returned if the user is not enrolled.
• If the user is not enrolled, you will get a association_required error, indicating the user needs to enroll to use MFA. Check Add an authenticator below on how to proceed.

• Authenticate With Resource Owner Password Grant and MFA
• Manage Authenticator Factors using the MFA API

POST https://{yourDomain}/oauth/token
Content-Type: application/x-www-form-urlencoded

client_id={yourClientId}&client_secret=YOUR_CLIENT_SECRET&mfa_token=MFA_TOKEN&grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-otp&otp=OTP_CODE

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'mfa_token=MFA_TOKEN&otp=OTP_CODE&grant_type=http://auth0.com/oauth/grant-type/mfa-otp&client_id={yourClientId}&client_secret=YOUR_CLIENT_SECRET'

var request = require("request");

var options = { method: 'POST',
  url: 'https://{yourDomain}/oauth/token',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  form:
   { mfa_token: 'MFA_TOKEN',
     otp: 'OTP_CODE',
     grant_type: 'http://auth0.com/oauth/grant-type/mfa-otp',
     client_id: '{yourClientId}',
     client_secret: 'YOUR_CLIENT_SECRET' }
   };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

RESPONSE SAMPLE FOR OTP:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token":"eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "expires_in":86400
}

Verifies multi-factor authentication (MFA) using a one-time password (OTP).

To verify MFA with an OTP, prompt the user to get the OTP code, then make a request to the /oauth/token endpoint. The request must have the OTP code, the mfa_token you received (from the mfa_required error), and the grant_type set to http://auth0.com/oauth/grant-type/mfa-otp.

The response is the same as responses for password or http://auth0.com/oauth/grant-type/password-realm grant types.

• Associate OTP Authenticators

POST https://{yourDomain}/oauth/token
Content-Type: application/x-www-form-urlencoded

client_id={yourClientId}&client_secret=YOUR_CLIENT_SECRET&mfa_token=MFA_TOKEN&grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&oob_code=OOB_CODE&binding_code=BINDING_CODE

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'client_id={yourClientId}&client_secret=YOUR_CLIENT_SECRET&mfa_token=MFA_TOKEN&grant_type=http://auth0.com/oauth/grant-type/mfa-oob&oob_code=OOB_CODE&binding_code=BINDING_CODE'

var request = require("request");

var options = { method: 'POST',
  url: 'https://{yourDomain}/oauth/token',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  form:
   { mfa_token: 'MFA_TOKEN',
     oob_code: "OOB_CODE",
     binding_code: "BINDING_CODE"
     grant_type: 'http://auth0.com/oauth/grant-type/mfa-oob',
     client_id: '{yourClientId}',
     client_secret: 'YOUR_CLIENT_SECRET' }
   };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

RESPONSE SAMPLE FOR PENDING CHALLENGE:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "error":"authorization_pending",
  "error_description":"Authorization pending: please repeat the request in a few seconds."
}

RESPONSE SAMPLE FOR VERIFIED CHALLENGE:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token":"eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "expires_in":86400
}

RESPONSE SAMPLE FOR REJECTED CHALLENGE:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "error":"invalid_grant",
  "error_description":"MFA Authorization rejected."
}

Verifies multi-factor authentication (MFA) using an out-of-band (OOB) challenge (either Push notification, SMS, or Voice).

To verify MFA using an OOB challenge, your application must make a request to /oauth/token with grant_type=http://auth0.com/oauth/grant-type/mfa-oob. Include the oob_code you received from the challenge response, as well as the mfa_token you received as part of mfa_required error.

The response to this request depends on the status of the underlying challenge verification:

• If the challenge has been accepted and verified, it will be the same as password or http://auth0.com/oauth/grant-type/password-realm grant types.
• If the challenge has been rejected, you will get an invalid_grant error, meaning that the challenge was rejected by the user. At this point you should stop polling, as this response is final.
• If the challenge verification is still pending (meaning it has not been accepted nor rejected), you will get an authorization_pending error, meaning that you must retry the same request a few seconds later. If you request too frequently, you will get a slow_down error.

When the challenge response includes a binding_method: prompt, your app needs to prompt the user for the binding_code and send it as part of the request. The binding_code is usually a 6-digit number (similar to an OTP) included as part of the challenge. No binding_code is necessary if the challenge response did not include a binding_method. In this scenario, the response will be immediate; you will receive an invalid_grant or an access_token as response.

• Associate Out-of-Band Authenticators

POST https://{yourDomain}/oauth/token
Content-Type: application/x-www-form-urlencoded

client_id={yourClientId}&client_secret=YOUR_CLIENT_SECRET&mfa_token=MFA_TOKEN&grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-recovery-code&recovery_code=RECOVERY_CODE

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'client_id={yourClientId}&client_secret=YOUR_CLIENT_SECRET&mfa_token=MFA_TOKEN&grant_type=http://auth0.com/oauth/grant-type/mfa-recovery-code&recovery_code=RECOVERY_CODE'

var request = require("request");

var options = { method: 'POST',
  url: 'https://{yourDomain}/oauth/token',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  form:
   { mfa_token: 'MFA_TOKEN',
     recovery_code: 'RECOVERY_CODE',
     grant_type: 'http://auth0.com/oauth/grant-type/mfa-recovery-code',
     client_id: '{yourClientId}',
     client_secret: 'YOUR_CLIENT_SECRET' }
   };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

RESPONSE SAMPLE FOR OTP:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token":"eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "expires_in":86400,
  "recovery_code": "abcdefg"
}

Verifies multi-factor authentication (MFA) using a recovery code.

Some multi-factor authentication (MFA) providers (such as Guardian) support using a recovery code to login. Use this method to authenticate when the user's enrolled device is unavailable, or the user cannot receive the challenge or accept it due to connectivity issues.

To verify MFA using a recovery code your app must prompt the user for the recovery code, and then make a request to oauth/token with grant_type=http://auth0.com/oauth/grant-type/mfa-recovery-code. Include the collected recovery code and the mfa_token from the mfa_required error. If the recovery code is accepted, the response will be the same as for password or http://auth0.com/oauth/grant-type/password-realm grant types. It might also include a recovery_code field, which the application must display to the end-user to be stored securely for future use.

POST https://{yourDomain}/mfa/associate
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN or MFA_TOKEN
{
  "client_id": "{yourClientId}",
  "client_secret": "YOUR_CLIENT_SECRET",
  "authenticator_types": ["oob"],
  "oob_channels": "sms",
  "phone_number": "+1 555 123456"
}

curl --request POST \
  --url 'https://{yourDomain}/mfa/associate' \
  --header 'authorization: Bearer ACCESS_TOKEN or MFA_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"client_id": "{yourClientId}", "client_secret": "YOUR_CLIENT_SECRET", "authenticator_types":["oob"], "oob_channels":"sms", "phone_number": "+1 555 123456"}'

var request = require("request");

var options = { method: 'POST',
  url: 'https://{yourDomain}/mfa/associate',
  headers: {
    'authorization': 'Bearer TOKEN',
    'content-type': 'application/json'
  },
  body:
   { client_id: '{yourClientId}',
     client_secret: 'YOUR_CLIENT_SECRET',
     authenticator_types: ["oob"],
     oob_channels: "sms",
     phone_number: "+1 555 123456" },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

RESPONSE SAMPLE FOR OOB (SMS channel):

HTTP/1.1 200 OK
Content-Type: application/json
{
  "oob_code": "Fe26.2**da6....",
  "binding_method":"prompt",
  "authenticator_type":"oob",
  "oob_channels":"sms",
  "recovery_codes":["ABCDEFGDRFK75ABYR7PH8TJA"],
}

RESPONSE SAMPLE FOR OOB (Auth0 channel):

HTTP/1.1 200 OK
Content-Type: application/json
{
  "oob_code": "Fe26.2**da6....",
  "barcode_uri":"otpauth://...",
  "authenticator_type":"oob",
  "oob_channels":"auth0",
  "recovery_codes":["ABCDEFGDRFK75ABYR7PH8TJA"],
}

RESPONSE SAMPLE FOR OTP:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "secret": "ABCDEFGMK5CE6WTZKRTTQRKUJVFXOVRF",
  "barcode_uri":"otpauth://...",
  "authenticator_type":"otp",
  "recovery_codes":["ABCDEFGDRFK75ABYR7PH8TJA"],
}

Associates or adds a new authenticator for multi-factor authentication (MFA).

If the user has active authenticators, an Access Token with the enroll scope and the audience set to https://{yourDomain}/mfa/ is required to use this endpoint.

If the user has no active authenticators, you can use the mfa_token from the mfa_required error in place of an Access Token for this request.

After an authenticator is added, it must be verified. To verify the authenticator, use the response values from the /mfa/associate request in place of the values returned from the /mfa/challenge endpoint and continue with the verification flow.

A recovery_codes field is included in the response the first time an authenticator is added. You can use recovery_codes to pass multi-factor authentication as shown on Verify with recovery code above.

To access this endpoint, you must set an Access Token at the Authorization header, with the following claims:

• scope: enroll
• audience: https://{yourDomain}/mfa/

• Multi-factor Authentication API

GET https://{yourDomain}/mfa/authenticators
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN

curl --request GET \
  --url 'https://{yourDomain}/mfa/authenticators' \
  --header 'authorization: Bearer ACCESS_TOKEN' \
  --header 'content-type: application/json'

var request = require("request");

var options = { method: 'GET',
  url: 'https://{yourDomain}/mfa/authenticators',
  headers: {
    'authorization': 'Bearer ACCESS_TOKEN',
    'content-type': 'application/json'
  },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

RESPONSE SAMPLE:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "id":"recovery-code|dev_DsvzGfZw2Fg5N3rI",
    "authenticator_type":"recovery-code",
    "active":true
  },
  {
    "id":"sms|dev_gB342kcL2K22S4yB",
    "authenticator_type":"oob",
    "oob_channels":"sms",
    "name":"+X XXXX1234",
    "active":true
  },
  {
    "id":"sms|dev_gB342kcL2K22S4yB",
    "authenticator_type":"oob",
    "oob_channels":"sms",
    "name":"+X XXXX1234",
    "active":false
  },
  {
    "id":"push|dev_433sJ7Mcwj9P794y",
    "authenticator_type":"oob",
    "oob_channels":"auth0",
    "name":"John's Device",
    "active":true
  },
    {
    "id":"totp|dev_LJaKaN5O3tjRFOw2",
    "authenticator_type":"otp",
    "active":true
  }
]

Returns a list of authenticators associated with your application.

To access this endpoint you must set an Access Token at the Authorization header, with the following claims:

• scope: read:authenticators
• audience: https://{yourDomain}/mfa/

• Manage Authenticators

DELETE https://{yourDomain}/mfa/authenticators/AUTHENTICATOR_ID
Authorization: Bearer ACCESS_TOKEN

curl --request DELETE \
  --url 'https://{yourDomain}/mfa/authenticators/AUTHENTICATOR_ID' \
  --header 'authorization: Bearer ACCESS_TOKEN' \

var request = require("request");

var options = { method: 'DELETE',
  url: 'https://{yourDomain}/mfa/authenticators/AUTHENTICATOR_ID',
  headers: {
    'authorization': 'Bearer ACCESS_TOKEN',
    'content-type': 'application/json'
  },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

RESPONSE SAMPLE:

HTTP/1.1 204 OK

Deletes an associated authenticator using its ID.

You can get authenticator IDs by listing the authenticators.

To access this endpoint, you must set an Access Token at the Authorization header, with the following claims:

• scope: remove:authenticators
• audience: https://{yourDomain}/mfa/

• Manage Authenticators

SAML

The SAML protocol is used mostly for third-party SaaS applications, like Salesforce and Box. Auth0 supports Service Provider (SP) and Identity Provider (IDP) initiated Sign On. To learn more, see SAML.

GET https://{yourDomain}/samlp/{yourClientId}?
  connection=CONNECTION

curl --request GET \
  --url 'https://{yourDomain}/samlp/{yourClientId}' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data '"connection"="CONNECTION"'

Use this endpoint to accept a SAML request to initiate a login.

Optionally, you can include a connection parameter to log in with a specific provider. If no connection is specified, the Auth0 Login Page will be shown.

Optionally, SP-initiated login requests can include an organization parameter to authenticate users in the context of an organization. To learn more, see Organizations.

• All the parameters of the SAML response can be modified with Rules.
• The SAML request AssertionConsumerServiceURL will be used to POST back the assertion. It must match one of the application's callback_URLs.

• SAML

GET https://{yourDomain}/samlp/metadata/{yourClientId}

curl --request GET \
  --url 'https://{yourDomain}/samlp/metadata/{yourClientId}'

This endpoint returns the SAML 2.0 metadata.

• SAML

POST https://{yourDomain}/login/callback?connection=CONNECTION
Content-Type: 'application/x-www-form-urlencoded'
  SAMLResponse=SAML_RESPONSE

curl --request POST \
  --url 'https://{yourDomain}/login/callback' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data '"connection":"CONNECTION", "SAMLResponse":"SAML_RESPONSE"'

This endpoint accepts an IdP-Initiated Sign On SAMLResponse from a SAML Identity Provider. The connection corresponding to the identity provider is specified in the query string. The user will be redirected to the application that is specified in the SAML Provider IdP-Initiated Sign On section.

1. At the Configuration tab, set the field Application (select the application you want to use for the test) and Connection (the name of the configured identity provider).

2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.

3. At the Other Flows tab, click SAML.

• SAML

WS-Federation

GET https://{yourDomain}/wsfed/{yourClientId}

curl --request GET \
  --url 'https://{yourDomain}/wsfed/{yourClientId}'

This endpoint accepts a WS-Federation request to initiate a login.

1. At the Configuration tab, set the field Application (select the application you want to use for the test) and Connection (the name of the configured identity provider).

2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.

3. At the Other Flows tab, click WS-Federation.

• The wtrealm parameter must be in one of these formats:
  • urn:clientID (for example, urn:{yourClientId})
  • If this parameter does not begin with a urn, the client.clientAliases array is used for look-up. This can only be set with the /api/v2/clients Management API.
• The whr parameter is mapped to the connection like this: urn:CONNECTION_NAME. For example, urn:google-oauth2 indicates login with Google. If there is no whr parameter included, the user will be directed to the Auth0 Login Page.

• WS-Federation

GET https://{yourDomain}/wsfed/FederationMetadata/2007-06/FederationMetadata.xml

curl --request GET \
  --url 'https://{yourDomain}/wsfed/FederationMetadata/2007-06/FederationMetadata.xml'

This endpoint returns the WS-Federation metadata.

• WS-Federation

Dynamic Application (Client) Registration

POST https://{yourDomain}/oidc/register
Content-Type: application/json
{
  "client_name": "YOUR-NEW-CLIENT-NAME",
  "redirect_uris": [],
  "token_endpoint_auth_method": "client_secret_post"
}

curl --request POST \
  --url https://{yourDomain}/oidc/register \
  --header 'content-type: application/json' \
  --data '{"client_name": "YOUR-NEW-CLIENT-NAME","redirect_uris": [], "token_endpoint_auth_method": "client_secret_post"}'

RESPONSE SAMPLE:

{
  "client_name": "My Dynamic Client",
  "client_id": "8SXWY6j3afl2CP5ntwEOpMdPxxy49Gt2",
  "client_secret": "Q5O...33P",
  "redirect_uris": [
    "https://client.example.com/callback",
    "https://client.example.com/callback2"
  ],
  "client_secret_expires_at": 0
}

With a name and the necessary callback URL, you can dynamically register a client with Auth0. No token is needed for this request.

Authorize Application

To begin an OAuth 2.0 Authorization flow, your application should first send the user to the authorization URL.

The purpose of this call is to obtain consent from the user to invoke the API (specified in audience) and do certain things (specified in scope) on behalf of the user. Auth0 will authenticate the user and obtain consent, unless consent has been previously given. If you alter the value in scope, Auth0 will require consent to be given again.

The OAuth 2.0 flows that require user authorization are:

• Authorization Code Flow
• Authorization Code Flow with Proof Key for Code Exchange (PKCE)
• Implicit Flow

On the other hand, the Resource Owner Password Grant and Client Credentials Flow do not use this endpoint since there is no user authorization involved. Instead, they directly invoke the POST /oauth/token endpoint to retrieve an Access Token.

Based on the OAuth 2.0 flow you are implementing, the parameters slightly change. To determine which flow is best suited for your case, refer to: Which OAuth 2.0 flow should I use?.

GET https://{yourDomain}/authorize?
  audience=API_IDENTIFIER&
  scope=SCOPE&
  response_type=code&
  client_id={yourClientId}&
  redirect_uri={https://yourApp/callback}&
  state=STATE

RESPONSE SAMPLE

HTTP/1.1 302 Found
Location: {https://yourApp/callback}?code=AUTHORIZATION_CODE&state=STATE

This is the OAuth 2.0 grant that regular web apps utilize in order to access an API.

1. At the Configuration tab, set the Client field to the application you want to use for the test.

2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.

3. At the OAuth2 / OIDC tab, set the fields Audience (to the unique identifier of the API you want to access), Response Type (set to code) and enable the Audience switch.

4. Click OAuth / OIDC Login. Following the redirect, the URL will contain the authorization code. Note, that the code will be set at the Authorization Code field so you can proceed with exchanging it for an Access Token.

• In order to improve compatibility for applications, Auth0 will now return profile information in a structured claim format as defined by the OIDC specification. This means that in order to add custom claims to ID Tokens or Access Tokens, they must conform to a namespaced format to avoid possible collisions with standard OIDC claims.
• Include offline_access to the scope request parameter to get a Refresh Token from POST /oauth/token. Make sure that the Allow Offline Access field is enabled in the API Settings.
• The redirect_uri value must be specified as a valid callback URL under your Application's Settings.
• Silent authentication lets you perform an authentication flow where Auth0 will only reply with redirects, and never with a login page. When an Access Token has expired, silent authentication can be used to retrieve a new one without user interaction, assuming the user's Single Sign-on session has not expired.

• Authorization Code Flow
• Call API Using the Authorization Code Flow
• State Parameter
• Silent Authentication

GET https://{yourDomain}/authorize?
  audience=API_IDENTIFIER&
  scope=SCOPE&
  response_type=code&
  client_id={yourClientId}&
  redirect_uri={https://yourApp/callback}&
  code_challenge=CODE_CHALLENGE&
  code_challenge_method=S256

RESPONSE SAMPLE

HTTP/1.1 302 Found
Location: {https://yourApp/callback}?code=AUTHORIZATION_CODE

This is the OAuth 2.0 grant that mobile apps utilize in order to access an API. Before starting with this flow, you need to generate and store a code_verifier, and using that, generate a code_challenge that will be sent in the authorization request.

1. At the Configuration tab, set the Application field to the app you want to use for the test.

2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.

3. At the OAuth2 / OIDC tab, set the fields Audience (to the unique identifier of the API you want to access), Response Type (set to code) and enable the Audience and PKCE switches.

4. Click OAuth / OIDC Login. Following the redirect, the URL will contain the authorization code. Note, that the code will be set at the Authorization Code field, and the Code Verifier will be automatically set as well, so you can proceed with exchanging the code for an Access Token.

• In order to improve compatibility for applications, Auth0 will now return profile information in a structured claim format as defined by the OIDC specification. This means that in order to add custom claims to ID Tokens or Access Tokens, they must conform to a namespaced format to avoid possible collisions with standard OIDC claims.
• Include offline_access to the scope request parameter to get a Refresh Token from POST /oauth/token. Make sure that the Allow Offline Access field is enabled in the API Settings.
• The redirect_uri value must be specified as a valid callback URL under your Application's Settings.
• Silent authentication lets you perform an authentication flow where Auth0 will only reply with redirects, and never with a login page. When an Access Token has expired, silent authentication can be used to retrieve a new one without user interaction, assuming the user's Single Sign-on (SSO) session has not expired.

• Authorization Code Flow with Proof Key for Code Exchange (PKCE)
• Call API Using the Authorization Code Flow with PKCE
• Silent Authentication

GET https://{yourDomain}/authorize?
  audience=API_IDENTIFIER&
  scope=SCOPE&
  response_type=token|id_token|id_token token&
  client_id={yourClientId}&
  redirect_uri={https://yourApp/callback}&
  state=STATE&
  nonce=NONCE

RESPONSE SAMPLE

HTTP/1.1 302 Found
Location: {https://yourApp/callback}#access_token=TOKEN&state=STATE&token_type=TYPE&expires_in=SECONDS

This is the OAuth 2.0 grant that web apps utilize in order to access an API.

1. At the Configuration tab, set the Application field to the app you want to use for the test.

2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your application Settings.

3. At the OAuth2 / OIDC tab, set the fields Audience (to the unique identifier of the API you want to access), Response Type (set to token) and enable the Audience switch.

4. Click OAuth / OIDC Login.

• The redirect_uri value must be specified as a valid callback URL under your Application's Settings.
• If response_type=token, after the user authenticates with the provider, this will redirect them to your application callback URL while passing the access_token in the address location.hash. This is used for Single-Page Apps and on Native Mobile SDKs.
• The Implicit Grant does not support the issuance of Refresh Tokens. You can use Silent Authentication instead.
• In order to improve compatibility for applications, Auth0 will now return profile information in a structured claim format as defined by the OIDC specification. This means that in order to add custom claims to ID Tokens or Access Tokens, they must conform to a namespaced format to avoid possible collisions with standard OIDC claims.
• Silent authentication lets you perform an authentication flow where Auth0 will only reply with redirects, and never with a login page. When an Access Token has expired, silent authentication can be used to retrieve a new one without user interaction, assuming the user's Single Sign-on (SSO) session has not expired.

• Implicit Flow
• State Parameter
• Mitigate replay attacks when using the Implicit Grant
• Silent Authentication

Get Device Code

To begin the Device Authorization Flow, your application should first request a device code.

POST https://{yourDomain}/oauth/device/code
Content-Type: application/x-www-form-urlencoded

client_id={yourClientId}&scope=SCOPE&audience=API_IDENTIFIER

curl --request POST \
  --url 'https://{yourDomain}/oauth/device/code' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'client_id={yourClientId}&scope=SCOPE&audience=API_IDENTIFIER'

var request = require("request");

var options = { method: 'POST',
  url: 'https://{yourDomain}/oauth/device/code',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  form:
   { client_id: '{yourClientId}',
     scope: 'SCOPE',
     audience: 'API_IDENTIFIER' }
   };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

RESPONSE SAMPLE

HTTP/1.1 200 OK
Content-Type: application/json
{
  "device_code":"GmRh...k9eS",
  "user_code":"WDJB-MJHT",
  "verification_uri":"https://{yourDomain}/device",
  "verification_uri_complete":"https://{yourDomain}/device?user_code=WDJB-MJHT",
  "expires_in":900, //in seconds
  "interval":5
}

This is the flow that input-constrained devices use to access an API. Use this endpoint to get a device code.

• Include offline_access to the scope request parameter to get a Refresh Token from POST /oauth/token. Make sure that the Allow Offline Access field is enabled in the API Settings.

• Device Authorization Flow
• Call API Using the Device Authorization Flow

Get Token

Use this endpoint to:

• Get an Access Token in order to call an API. Optionally, you can also retrieve an ID Token and a Refresh Token.
• Refresh your Access Token using a Refresh Token you got during authorization.

Note that the only OAuth 2.0 flows that can retrieve a Refresh Token are:

• Authorization Code Flow (Authorization Code)
• Authorization Code Flow with PKCE (Authorization Code with PKCE)
• Resource Owner Password
• Device Authorization Flow
• Token Exchange*

* Only for certain native social profiles

POST https://{yourDomain}/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id={yourClientId}&client_secret=YOUR_CLIENT_SECRET&code=AUTHORIZATION_CODE&redirect_uri={https://yourApp/callback}

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code&client_id={yourClientId}&client_secret=YOUR_CLIENT_SECRET&code=AUTHORIZATION_CODE&redirect_uri={https://yourApp/callback}'

var request = require("request");

var options = { method: 'POST',
  url: 'https://{yourDomain}/oauth/token',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  form:
   { grant_type: 'authorization_code',
     client_id: '{yourClientId}',
     client_secret: 'YOUR_CLIENT_SECRET',
     code: 'AUTHORIZATION_CODE',
     redirect_uri: '{https://yourApp/callback}' }
   };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

RESPONSE SAMPLE:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token":"eyJz93a...k4laUWw",
  "refresh_token":"GEbRxBN...edjnXbL",
  "id_token":"eyJ0XAi...4faeEoQ",
  "token_type":"Bearer",
  "expires_in":86400
}

This is the flow that regular web apps use to access an API. Use this endpoint to exchange an Authorization Code for a Token.

If you have just executed the Authorization Code Grant, you should already have a code set at the Authorization Code field of the OAuth2 / OIDC tab. If so, click OAuth2 Code Exchange; otherwise, follow the instructions.

1. At the Configuration tab, set the Application field to the application you want to use for the test.

2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.

3. At the OAuth2 / OIDC tab, set the field Authorization Code to the code you retrieved from the Authorization Code Grant. Click OAuth2 Code Exchange.

• Authorization Code Flow
• Call API using Authorization Code Flow

POST https://{yourDomain}/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id={yourClientId}&code_verifier=CODE_VERIFIER&code=AUTHORIZATION_CODE&redirect_uri={https://yourApp/callback}

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code&client_id={yourClientId}&code_verifier=CODE_VERIFIER&code=AUTHORIZATION_CODE&redirect_uri={https://yourApp/callback}'

var request = require("request");

var options = { method: 'POST',
  url: 'https://{yourDomain}/oauth/token',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  form: {
    grant_type:"authorization_code",
    client_id: "{yourClientId}",
    code_verifier: "CODE_VERIFIER",
    code: "AUTHORIZATION_CODE",
    redirect_uri: "{https://yourApp/callback}", } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

RESPONSE SAMPLE:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token":"eyJz93a...k4laUWw",
  "refresh_token":"GEbRxBN...edjnXbL",
  "id_token":"eyJ0XAi...4faeEoQ",
  "token_type":"Bearer",
  "expires_in":86400
}

This is the flow that mobile apps use to access an API. Use this endpoint to exchange an Authorization Code for a Token.

If you have just executed the Authorization Code Grant (PKCE) you should already have the Authorization Code and Code Verifier fields, of the OAuth2 / OIDC tab, set. If so, click OAuth2 Code Exchange, otherwise follow the instructions.

1. At the Configuration tab, set the Client field to the application you want to use for the test.

2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.

3. At the OAuth2 / OIDC tab, set the field Authorization Code to the code you retrieved from Authorization Code Grant, and the Code Verifier to the key. Click OAuth2 Code Exchange.

• Authorization Code Flow with Proof Key for Code Exchange (PKCE)
• Call API Using the Authorization Code Flow with PKCE

POST https://{yourDomain}/oauth/token
Content-Type: application/x-www-form-urlencoded

audience=API_IDENTIFIER&grant_type=client_credentials&client_id={yourClientId}&client_secret=YOUR_CLIENT_SECRET

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'audience=API_IDENTIFIER&grant_type=client_credentials&client_id={yourClientId}&client_secret=YOUR_CLIENT_SECRET'

var request = require("request");

var options = { method: 'POST',
  url: 'https://{yourDomain}/oauth/token',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  form:
   { client_id: '{yourClientId}',
     client_secret: 'YOUR_CLIENT_SECRET',
     audience: 'API_IDENTIFIER',
     grant_type: 'client_credentials' }
   };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

RESPONSE SAMPLE:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token":"eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "expires_in":86400
}

This is the OAuth 2.0 grant that server processes use to access an API. Use this endpoint to directly request an Access Token by using the Client's credentials (a Client ID and a Client Secret).

1. At the Configuration tab, set the Client field to the application you want to use for the test.

2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.

3. At the OAuth2 / OIDC tab, click OAuth2 Client Credentials.

• Client Credentials Flow
• Call API using the Client Credentials Flow
• Setting up a Client Grant using the Management Dashboard
• Asking for Access Tokens for a Client Credentials Grant

POST https://{yourDomain}/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=USERNAME&password=PASSWORD&audience=API_IDENTIFIER&scope=SCOPE&client_id={yourClientId}&client_secret=YOUR_CLIENT_SECRET

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=password&username=USERNAME&password=PASSWORD&audience=API_IDENTIFIER&scope=SCOPE&client_id={yourClientId}&client_secret=YOUR_CLIENT_SECRET'

var request = require("request");

var options = { method: 'POST',
  url: 'https://{yourDomain}/oauth/token',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  form:
   { grant_type: 'password',
     username: 'USERNAME',
     password: 'PASSWORD',
     audience: 'API_IDENTIFIER',
     scope: 'SCOPE',
     client_id: '{yourClientId}',
     client_secret: 'YOUR_CLIENT_SECRET' }
   };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

RESPONSE SAMPLE:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token":"eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "expires_in":86400
}

This is the OAuth 2.0 grant that highly-trusted apps use to access an API. In this flow, the end-user is asked to fill in credentials (username/password), typically using an interactive form in the user-agent (browser). This information is sent to the backend and from there to Auth0. It is therefore imperative that the application is absolutely trusted with this information. For single-page applications and native/mobile apps, we recommend using web flows instead.

1. At the Configuration tab, set the Client field to the application you want to use for the test.

2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.

3. At the OAuth2 / OIDC tab, set the Username and Password, and click Password Grant.

• The scopes issued to the application may differ from the scopes requested. In this case, a scope parameter will be included in the response JSON.
• If you don't request specific scopes, all scopes defined for the audience will be returned due to the implied trust to the application in this grant. You can customize the scopes returned in a rule. For more information, refer to Calling APIs from Highly Trusted Applications.
• To add realm support set the grant_type to http://auth0.com/oauth/grant-type/password-realm, and the realm to the realm the user belongs. This maps to a connection in Auth0. For example, if you have configured a database connection for your internal employees and you have named the connection employees, then use this value. For more information on how to implement this refer to: Realm Support.
• In addition to username and password, Auth0 may also require the end-user to provide an additional factor as proof of identity before issuing the requested scopes. In this case, the request described above will return an mfa_required error along with an mfa_token. You can use these tokens to request a challenge for the possession factor and validate it accordingly. For details refer to Resource Owner Password and MFA.

• Calling APIs from Highly-Trusted Applications
• Executing the Resource Owner Password Grant
• Multi-factor Authentication and Resource Owner Password

POST https://{yourDomain}/oauth/token
Content-Type: application/x-www-form-urlencoded

client_id={yourClientId}&device_code=YOUR_DEVICE_CODE&grant_type=urn:ietf:params:oauth:grant-type:device_code

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'client_id={yourClientId}&device_code=YOUR_DEVICE_CODE&grant_type=urn:ietf:params:oauth:grant-type:device_code'

var request = require("request");

var options = { method: 'POST',
  url: 'https://{yourDomain}/oauth/token',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  form:
   { client_id: '{yourClientId}',
     device_code: 'YOUR_DEVICE_CODE',
     grant_type: 'urn:ietf:params:oauth:grant-type:device_code' }
   };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

RESPONSE SAMPLE:

HTTP/1.1 200 OK
Content-Type: application/json
{
   "access_token": "eyJz93a...k4laUWw",
   "id_token": "eyJ...0NE",
   "refresh_token": "eyJ...MoQ",
   "scope": "...",
   "expires_in": 86400,
   "token_type": "Bearer"
}

HTTP/1.1 403 Forbidden
Content-Type: application/json
 { 
  // Can be retried
  "error": "authorization_pending",
  "error_description": "User has yet to authorize device code."
 }

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
 { 
  // Can be retried
  "error": "slow_down",
  "error_description": "You are polling faster than the specified interval of 5 seconds."
 }

HTTP/1.1 403 Forbidden
Content-Type: application/json
 { 
    // Cannot be retried; transaction failed
    "error": "access_denied|invalid_grant|...",
    "error_description": "Failure: User cancelled the confirmation prompt or consent page; the code expired; there was an error."
 }

This is the OAuth 2.0 grant that input-constrained devices use to access an API. Poll this endpoint using the interval returned with your device code to directly request an Access Token using the application's credentials (a Client ID) and a device code.

• Because you will be polling this endpoint (using the interval from the initial response to determine frequency) while waiting for the user to go to the verification URL and enter their user code, you will likely receive at least one failure before receiving a successful response. See sample responses for possible responses.

• Device Authorization Flow
• Call API using the Device Authorization Flow
• Setting up a Device Code Grant using the Management Dashboard

POST https://{yourDomain}/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id={yourClientId}&client_secret=YOUR_CLIENT_SECRET&refresh_token=YOUR_REFRESH_TOKEN

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=refresh_token&client_id={yourClientId}&client_secret=YOUR_CLIENT_SECRET&refresh_token=YOUR_REFRESH_TOKEN'

var request = require("request");

var options = { method: 'POST',
  url: 'https://{yourDomain}/oauth/token',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  form:
   { grant_type: 'refresh_token',
     client_id: '{yourClientId}',
     client_secret: 'YOUR_CLIENT_SECRET',
     refresh_token: 'YOUR_REFRESH_TOKEN'}
   };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

RESPONSE SAMPLE:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token": "eyJ...MoQ",
  "expires_in": 86400,
  "scope": "openid offline_access",
  "id_token": "eyJ...0NE",
  "token_type": "Bearer"
}

Use this endpoint to refresh an Access Token using the Refresh Token you got during authorization.

1. At the Configuration tab, set the Client field to the client you want to use for the test.

2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.

3. At the OAuth2 / OIDC tab, set the field Refresh Token to the Refresh Token you have. Click OAuth2 Refresh Token Exchange.

• Refresh Tokens

POST https://{yourDomain}/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange&subject_token=SUBJECT_TOKEN&subject_token_type=SUBJECT_TOKEN_TYPE&client_id={yourClientId}&audience=API_IDENTIFIER&scope=SCOPE

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange&subject_token=SUBJECT_TOKEN&subject_token_type=SUBJECT_TOKEN_TYPE&client_id={yourClientId}&audience=API_IDENTIFIER&scope=SCOPE'
 }'

var request = require("request");

var options = { method: 'POST',
  url: 'https://{yourDomain}/oauth/token',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  form:
   { grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
     subject_token: 'SUBJECT_TOKEN',
     subject_token_type: 'SUBJECT_TOKEN_TYPE',
     client_id: '{yourClientId}',
     audience: 'API_IDENTIFIER',
     scope: 'SCOPE',
   };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

RESPONSE SAMPLE:

HTTP/1.1 200 OK
Content-Type: application/json
{ 
  "access_token": "eyJz93a...k4laUWw",
  "id_token": "eyJ...0NE",
  "refresh_token": "eyJ...MoQ",
  "expires_in":86400,
  "token_type":"Bearer"
}

When a non-browser-based solution (such as a mobile platform's SDK) authenticates the user, the authentication will commonly result in artifacts being returned to application code. In such situations, this grant type allows for the Auth0 platform to accept artifacts from trusted sources and issue tokens in response. In this way, apps making use of non-browser-based authentication mechanisms (as are common in native apps) can still retrieve Auth0 tokens without asking for further user interaction.

Artifacts returned by this flow (and the contents thereof) will be determined by the subject_token_type and configuration settings of the tenant.

• The scopes issued to the application may differ from the scopes requested. In this case, a scope parameter will be included in the response JSON.
• If you don't request specific scopes, all scopes defined for the audience will be returned due to the implied trust to the application in this grant. You can customize the scopes returned in a rule. For more information, refer to Calling APIs from Highly Trusted Applications.

• Add Sign In with Apple to Native iOS Apps
• iOS Swift - Sign In with Apple Quickstart

Revoke Refresh Token

POST https://{yourDomain}/oauth/revoke
Content-Type: application/json
{
  "client_id": "{yourClientId}",
  "client_secret": "YOUR_CLIENT_SECRET",
  "token": "YOUR_REFRESH_TOKEN",
}

curl --request POST \
  --url 'https://{yourDomain}/oauth/revoke' \
  --header 'content-type: application/json' \
  --data '{ "client_id": "{yourClientId}", "client_secret": "YOUR_CLIENT_SECRET", "token": "YOUR_REFRESH_TOKEN" }'

var request = require("request");

var options = { method: 'POST',
  url: 'https://{yourDomain}/oauth/revoke',
  headers: { 'content-type': 'application/json' },
  body: 
   { client_id: '{yourClientId}',
     client_secret: 'YOUR_CLIENT_SECRET',
     token: 'YOUR_REFRESH_TOKEN' },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

RESPONSE SAMPLE:

HTTP/1.1 200 OK
(empty-response-body)

Use this endpoint to invalidate a Refresh Token if it has been compromised.

The behaviour of this endpoint depends on the state of the Refresh Token Revocation Deletes Grant toggle. If this toggle is enabled, then each revocation request invalidates not only the specific token, but all other tokens based on the same authorization grant. This means that all Refresh Tokens that have been issued for the same user, application, and audience will be revoked. If this toggle is disabled, then only the refresh token is revoked, while the grant is left intact.

• For non-confidential applications that cannot keep the Client Secret safe (for example, native apps), the endpoint supports passing no Client Secret but the application itself must have the property tokenEndpointAuthMethod set to none. You can do this either from the UI (Dashboard > Applications > Application Settings) or using the Management API.

For the complete error code reference for this endpoint refer to Errors > POST /oauth/revoke.

• Refresh Tokens

Login

POST https://{yourDomain}/oauth/access_token
Content-Type: application/json
{
  "client_id": "{yourClientId}",
  "access_token": "ACCESS_TOKEN",
  "connection": "CONNECTION",
  "scope": "SCOPE"
}

curl --request POST \
  --url 'https://{yourDomain}/oauth/access_token' \
  --header 'content-type: application/json' \
  --data '{"client_id":"{yourClientId}", "access_token":"ACCESS_TOKEN", "connection":"CONNECTION", "scope":"SCOPE"}'

var url = 'https://' + {yourDomain} + '/oauth/access_token';
var params = 'client_id={yourClientId}&access_token={ACCESS_TOKEN}&connection={CONNECTION}&scope={SCOPE}';

var xhr = new XMLHttpRequest();

xhr.open('POST', url);
xhr.setRequestHeader('Content-Type', 'application/json');

xhr.onload = function() {
  if (xhr.status == 200) {
    fetchProfile();
  } else {
    alert("Request failed: " + xhr.statusText);
  }
};

xhr.send(params);

RESPONSE SAMPLE:

{
  "id_token": "eyJ0eXAiOiJKV1Qi...",
  "access_token": "A9CvPwFojaBI...",
  "token_type": "bearer"
}

Given the social provider's Access Token and the connection, this endpoint will authenticate the user with the provider and return a JSON with the Access Token and, optionally, an ID Token. This endpoint only works for Facebook, Google, Twitter, and Weibo.

• The profile scope value requests access to the End-User's default profile Claims, which are: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at.

• The email scope value requests access to the email and email_verified Claims.

For the complete error code reference for this endpoint refer to Errors > POST /oauth/access_token.

• Call an Identity Provider API

• Identity Provider Access Tokens

• Add scopes/permissions to call Identity Provider's APIs

POST https://{yourDomain}/oauth/ro
Content-Type: application/json
{
  "client_id": "{yourClientId}",
  "username": "USERNAME",
  "password": "PASSWORD",
  "connection": "CONNECTION",
  "scope": "openid"
}

curl --request POST \
  --url 'https://{yourDomain}/oauth/ro' \
  --header 'content-type: application/json' \
  --data '{"client_id":"{yourClientId}", "username":"USERNAME", "password":"PASSWORD", "connection":"CONNECTION", "scope":"openid"}'

// Script uses auth0.js. See Remarks for details.
<script src="https://cdn.auth0.com/js/auth0/9.11/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize application
  var webAuth = new auth0.WebAuth({
    domain:       '{yourDomain}',
    clientID:     '{yourClientId}'
  });

  // Trigger login using redirect with credentials to enterprise connections
  webAuth.redirect.loginWithCredentials({
    connection: 'Username-Password-Authentication',
    username: 'testuser',
    password: 'testpass',
    scope: 'openid'
  });

  // Trigger login using popup mode with credentials to enterprise connections
  webAuth.popup.loginWithCredentials({
    connection: 'Username-Password-Authentication',
    username: 'testuser',
    password: 'testpass',
    scope: 'openid'
  });

  // The client.login method allows for non redirect auth using custom database connections, using /oauth/token.
  webAuth.client.login({
    realm: 'tests',
    username: 'testuser',
    password: 'testpass',
    scope: 'openid profile',
    audience: 'urn:test'
  });
</script>

Use this endpoint for API-based (active) authentication. Given the user credentials and the connection specified, it will do the authentication on the provider and return a JSON with the Access Token and ID Token.

1. At the Configuration tab, set the fields Application (select the application you want to use for the test) and Connection (the name of the social connection to use).

2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.

3. At the OAuth2 / OIDC tab, set Username and Password. Click Resource Owner Endpoint.

• This endpoint only works for database connections, passwordless connections, Active Directory/LDAP, Windows Azure AD and ADFS.

• The main difference between passive and active authentication is that the former happens in the browser through the Auth0 Login Page and the latter can be invoked from anywhere (a script, server to server, and so forth).

• The sample auth0.js script uses the library version 8. If you are using auth0.js version 7, please see this reference guide.

For the complete error code reference for this endpoint, refer to Errors > POST /oauth/ro.

• Database Identity Providers

• Rate Limits on User/Password Authentication

• Active Directory/LDAP Connector

User Profile

POST https://{yourDomain}/tokeninfo
Content-Type: application/json
{
  "id_token": "ID_TOKEN"
}

curl --request POST \
  --url 'https://{yourDomain}/tokeninfo' \
  --header 'content-type: application/json' \
  --data '{"id_token":""}'

<script src="https://cdn.auth0.com/js/auth0/9.11/auth0.min.js"></script>
<script type="text/javascript">
  var webAuth = new auth0.WebAuth({
    domain:       '{yourDomain}',
    clientID:     '{yourClientId}'
  });
</script>

webAuth.parseHash(window.location.hash, function(err, authResult) {
  if (err) {
    return console.log(err);
  }

  webAuth.client.userInfo(authResult.accessToken, function(err, user) {
    // Now you have the user's information
  });
});

RESPONSE SAMPLE:

{
  "email_verified": false,
  "email": "foo@bar.com",
  "clientID": "q2hnj2iug0...",
  "updated_at": "2016-12-08T14:26:59.923Z",
  "name": "foo@bar.com",
  "picture": "https://s.gravatar.com/avatar/foobar.png",
  "user_id": "auth0|58454...",
  "nickname": "foo.bar",
  "identities": [
    {
      "user_id": "58454...",
      "provider": "auth0",
      "connection": "Username-Password-Authentication",
      "isSocial": false
    }
  ],
  "created_at": "2016-12-05T11:16:59.640Z",
  "global_client_id": "dfas76s..."
}

This endpoint validates a JSON Web Token (JWT) (signature and expiration) and returns the user information associated with the user id sub property of the token.

• This endpoint will return three HTTP Response Headers, that provide relevant data on its rate limits:
  • X-RateLimit-Limit: Number of requests allowed per minute.
  • X-RateLimit-Remaining: Number of requests available. Each new request reduces this number by 1. For each minute that passes, requests are added back, so this number increases by 1 each time.
  • X-RateLimit-Reset: Remaining time until the rate limit (X-RateLimit-Limit) resets. The value is in UTC epoch seconds.

• User Profile Struture

• Auth0 API Rate Limit Policy

Account Linking

GET https://{yourDomain}/authorize?
  response_type=code|token&
  client_id={yourClientId}&
  connection=CONNECTION&
  redirect_uri={https://yourApp/callback}&
  access_token=LOGGED_IN_USER_ACCESS_TOKEN

Call this endpoint when a user wants to link a second authentication method (for example, a user/password database connection, with Facebook).

This endpoint will trigger the login flow to link an existing account with a new one. This will return a 302 redirect to the connection that the current user wants to add. The user is identified by the Access Token that was returned on login success.

• The redirect_uri value must be specified as a valid callback URL under your Application's Settings.

• Link User Accounts
• Link User Accounts Initiated by Users Scenario
• Link User Accounts Server-Side Scenario

POST https://{yourDomain}/login/unlink
Content-Type: application/json
{
  "access_token": "LOGGED_IN_USER_ACCESS_TOKEN", // Primary identity Access Token
  "user_id": "LINKED_USER_ID" // (provider|id)
}

curl --request POST \
  --url 'https://{yourDomain}/login/unlink' \
  --header 'content-type: application/json' \
  --data '{"access_token": "LOGGED_IN_USER_ACCESS_TOKEN", "user_id": "LINKED_USER_ID"}'

var url = 'https://' + {yourDomain} + '/login/unlink';
var params = 'access_token=LOGGED_IN_USER_ACCESS_TOKEN&user_id=' + localStorage.getItem('user_id');

var xhr = new XMLHttpRequest();
xhr.open('POST', url);
xhr.setRequestHeader('Content-Type', 'application/json');

xhr.onload = function() {
  if (xhr.status == 200) {
    fetchProfile();
  } else {
    alert("Request failed: " + xhr.statusText);
  }
};

xhr.send(params);

Given a logged-in user's access_token and user_id, this endpoint will unlink a user's account from the identity provider.

• Unlink User Accounts

Delegation

POST https://{yourDomain}/delegation
Content-Type: application/json
{
  "client_id": "{yourClientId}",
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "id_token" or "refresh_token" : "TOKEN",
  "target": "TARGET_CLIENT_ID",
  "scope": "openid",
  "api_type": "API_TYPE"
}

curl --request POST \
  --url 'https://{yourDomain}/delegation' \
  --header 'content-type: application/json' \
  --data '{"client_id":"{yourClientId}", "grant_type":"urn:ietf:params:oauth:grant-type:jwt-bearer", "id_token|refresh_token":"TOKEN", "target":"TARGET_CLIENT_ID", "scope":"openid", "api_type":"API_TYPE"}'

// Delegation is not supported in version 8 of auth0.js.
// For a version 7 sample refer to: https://auth0.com/docs/libraries/auth0js/v7#delegation-token-request

A delegation token can be obtained and used when an application needs to call the API of an Application Addon, such as Firebase or SAP, registered and configured in Auth0, in the same tenant as the calling program.

Given an existing token, this endpoint will generate a new token signed with the target app' secret. This is used to flow the identity of the user from the application to an API.

1. At the Configuration tab, set the Application field to the app you want to use for the test.

2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.

3. At the OAuth2 / OIDC tab, set the fields ID Token, Refresh Token and Target Client ID. Click Delegation.

• The profile scope value requests access to the End-User's default profile Claims, which are: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at.

• The email scope value requests access to the email and email_verified Claims.

• Delegation is not supported in version 8 of auth0.js. For a sample in version 7 of the library, refer to Delegation Token Request.

• This endpoint limits up to 10 requests per minute from the same IP address with the same user_id.

• This endpoint will return three HTTP Response Headers, that provide relevant data on its rate limits:

  • X-RateLimit-Limit: Number of requests allowed per minute.
  • X-RateLimit-Remaining: Number of requests available. Each new request reduces this number by 1. For each minute that passes, requests are added back, so this number increases by 1 each time.
  • X-RateLimit-Reset: Remaining time until the rate limit (X-RateLimit-Limit) resets. The value is in UTC epoch seconds.

• Delegation Tokens

• Auth0 API Rate Limit Policy

Impersonation

POST https://{yourDomain}/users/{user_id}/impersonate
Content-Type:   application/json
Authorization:  'Bearer {ACCESS_TOKEN}'
{
  protocol: "PROTOCOL",
  impersonator_id: "IMPERSONATOR_ID",
  client_id: "{yourClientId}",
  additionalParameters: [
    "response_type": "code",
    "state": "STATE"
  ]
}

curl --request POST \
  --url 'https://{yourDomain}/users/{user_id}/impersonate' \
  --header 'Authorization: Bearer {ACCESS_TOKEN}' \
  --header 'content-type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data '{"protocol":"PROTOCOL", "impersonator_id":"IMPERSONATOR_ID", "client_id":"{yourClientId}", "additionalParameters": {"response_type": "code", "state": "STATE"}}'

var url = 'https://' + {yourDomain} + '/users/' + localStorage.getItem('user_id') + '/impersonate';
var params = 'protocol=PROTOCOL&impersonator_id=IMPERSONATOR_ID&client_id={yourClientId}';

var xhr = new XMLHttpRequest();

xhr.open('POST', url);
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.setRequestHeader('Authorization', 'Bearer ' + localStorage.getItem('access_token'));

xhr.onload = function() {
  if (xhr.status == 200) {
    fetchProfile();
  } else {
    alert("Request failed: " + xhr.statusText);
  }
};

xhr.send(params);

RESPONSE SAMPLE:

https:/YOUR_DOMAIN/users/IMPERSONATOR_ID/impersonate?&bewit=WFh0MUtm...

Use this endpoint to obtain an impersonation URL to login as another user. Useful for troubleshooting.

• This endpoint can only be used with Global Client credentials.

• To distinguish between real logins and impersonation logins, the profile of the impersonated user will contain additional impersonated and impersonator properties. For example: "impersonated": true, "impersonator": {"user_id": "auth0|...", "email": "admin@example.com"}.

• For a regular web app, you should set the additionalParameters: set the response_type to be code, the callback_url to be the callback URL to which Auth0 will redirect with the authorization code, and the scope to be the JWT claims that you want included in the JWT.

Resource Owner

POST https://{yourDomain}/oauth/ro
Content-Type: application/json
{
  "client_id": "{yourClientId}",
  "connection": "CONNECTION",
  "grant_type": "password",
  "username": "USERNAME",
  "password": "PASSWORD",
  "scope": "SCOPE",
  "id_token": "ID_TOKEN",
  "device": "DEVICE"
}

curl --request POST \
  --url 'https://{yourDomain}/oauth/ro' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{ "client_id": "{yourClientId}", "connection": "CONNECTION", "grant_type": "password", "username": "USERNAME", "password": "PASSWORD", "scope": "SCOPE", "id_token": "ID_TOKEN", "device": "DEVICE" }'

var request = require("request");

var options = { method: 'POST',
  url: 'https://{yourDomain}/oauth/ro',
  headers: { 'content-type': 'application/json', 'accept': 'application/json' },
  body:
   { connection: 'CONNECTION',
     grant_type: 'PASSWORD',
     username: 'USERNAME',
     client_id: '{yourClientId}',
     password: 'PASSWORD',
     scope: 'SCOPE',
     id_token: 'ID_TOKEN',
     device: 'DEVICE'},
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

RESPONSE SAMPLE:

{
  "access_token": "eyJz93a...",
  "id_token": "eyJ0XAi...",
  "token_type": "Bearer"
}

Given the user's credentials, this endpoint will authenticate the user with the provider and return a JSON object with the Access Token and an ID Token.

1. At the Configuration tab, set the Application field to the application you want to use for the test, and Connection to the name of the connection to use.

2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.

3. At the OAuth2 / OIDC tab, set the Username and Password, and click Resource Owner Endpoint.

• This endpoint only works for database connections, passwordless connections, Active Directory/LDAP, Windows Azure AD and ADFS.

• The profile scope value requests access to the End-User's default profile Claims, which are: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at.

• The email scope value requests access to the email and email_verified Claims.

For the complete error code reference for this endpoint refer to Errors > POST /oauth/ro.

• Calling APIs from Highly Trusted Applications

Standard Error Responses

The Authentication API may return the following HTTP Status Codes:

Status	Description	Message
400	Bad Request	{"error": "invalid_request", "error_description": "..."}
400	Bad Request	{"error": "invalid_scope", "error_description": "..."}
400	Bad Request	{"error": "invalid_scope", "error_description": "Scope must be an array or a string"}
401	Unauthorized	{"error": "invalid_client", "error_description": "..."}
401	Unauthorized	{"error": "requires_validation", "error_description": "Suspicious request requires verification"}
403	Forbidden	{"error": "unauthorized_client", "error_description": "..."}
403	Forbidden	{"error": "access_denied", "error_description": "..."}
403	Forbidden	{"error": "access_denied", "error_description": "Unknown or invalid refresh token"}
403	Forbidden	{"error": "invalid_grant", "error_description": "..."}
404	Not Found	{"error": "endpoint_disabled", "error_description": "..."}
405	Method Not Allowed	{"error": "method_not_allowed", "error_description": "..."}
429	Too Many Requests	{"error": "too_many_requests", "error_description": "..."}
500	Internal Server Error
501	Not Implemented	{"error": "unsupported_response_type", "error_description": "..."}
501	Not Implemented	{"error": "unsupported_grant_type", "error_description": "..."}
503	Service Unavailable	{"error": "temporarily_unavailable", "error_description": "..."}

POST /oauth/revoke

Status	Description
200	{"error": "invalid_request", "error_description": "..."} The Refresh Token is revoked, does not exist, or was not issued to the client making the revocation request.
400	{"error": "invalid_request", "error_description": "..."} The required parameters were not sent in the request.
401	<{"error": "invalid_client", "error_description": "..."} The request is not authorized. Check that the client credentials (client_id and client_secret) are present in the request and hold valid values.

POST /oauth/access_token

Status	Response
400	{"error": "invalid_request", "error_description": "the connection was disabled"} The connection is not active or not enabled for your client_id
400	{"error": "invalid_request", "error_description": "the connection was not found"}
400	{"error": "invalid_request", "error_description": "missing client_id parameter"}
400	{"error": "invalid_request", "error_description": "missing access_token parameter"}
401	{"error": "invalid_request", "error_description": "invalid access_token: invalid_token"} The access_token is invalid or does not contain the scope you set
403	{"error": "unauthorized_client", "error_description": "invalid client"}

POST /oauth/ro

Status	Description
400	{"error": "invalid_request", "error_description": "missing device parameter"} You need to provide a device name for the caller device (like a browser, app, and so on)
400	{"error": "invalid_request", "error_description": "missing id_token parameter"} For this grant type you need to provide a JWT ID Token
400	{"error": "invalid_grant", "error_description": "..."} Errors related to an invalid ID Token or user

Status	Description
400	{"error": "invalid_request", "error_description": "scope parameter must be a string"} Incorrect scope formatting; each scope must be separated by whitespace
400	{"error": "invalid_request", "error_description": "specified strategy does not support requested operation"} The connection/provider does not implement username/password authentication
401	{"error": "invalid_user_password", "error_description": "Wrong email or password."}
401	{"error": "unauthorized", "error_description": "user is blocked"}
401	{ "error": "password_leaked", "error_description": "This login has been blocked because your password has been leaked in another website. We’ve sent you an email with instructions on how to unblock it."}
401	{ "error": "requires_verification", "error_description": "Suspicious request requires verification" }
429	{"error": "too_many_attempts", "error_description": "..."} Some attack protection features will return this error
429	{"error": "too_many_logins", "error_description": "..."} Some attack protection features will return this error

Status	Description
400	{"error": "invalid_request", "error_description": "missing client_id parameter"}
400	{"error": "invalid_request", "error_description": "the connection was disabled"} Check the connection in the dashboard, you may have turned it off for the provided client_id
400	{"error": "invalid_request", "error_description": "The connection is not yet configured..."} The connection is not properly configured with custom scripts
400	{"error": "invalid_request", "error_description": "the connection was not found for tenant..."} The connection does not belong to the tenant; check your base url
400	{"error": "invalid_request", "error_description": "Fields with "." are not allowed, please remove all dotted fields..."} If you are using rules, some field name contains dots
403	{"error": "unauthorized_client", "error_description": "invalid client"} The provided client_id is not valid
403	{"error": "access_denied", "error_description": "..."} Validation of specific points raised an access issue

POST /passwordless/verify

Status	Description
400	{"error": "invalid_request", "error_description": "missing username parameter"}
400	{"error": "invalid_request", "error_description": "missing password parameter"}
400	{"error": "invalid_request", "error_description": "missing connection parameter"}
400	{"error": "invalid_request", "error_description": "scope parameter must be a string"} Incorrect scope formatting; each scope must be separated by whitespace
400	{"error": "invalid_request", "error_description": "missing client_id parameter"}
400	{"error": "invalid_request", "error_description": "the connection was not found"}
400	{"error": "invalid_request", "error_description": "the connection was disabled"} Check the connection in the dashboard, you may have turned it off for the provided client_id
400	{"error": "invalid_request", "error_description": "the connection was not found for tenant..."} The connection does not belong to the tenant; check your base url
400	{"error": "invalid_request", "error_description": "Fields with "." are not allowed, please remove all dotted fields..."} If you are using rules, some field name contains dots
401	{"error": "invalid_user_password", "error_description": "Wrong email or password."}
401	{"error": "unauthorized", "error_description": "user is blocked"}
403	{"error": "unauthorized_client", "error_description": "invalid client"} The provided client_id is not valid
403	{"error": "access_denied", "error_description": "..."} Validation of specific points raised an access issue
429	{"error": "too_many_attempts", "error_description": "..."} Some attack protection features will return this error
429	{"error": "too_many_logins", "error_description": "..."} Some attack protection features will return this error

POST /passwordless/start

Status	Response
400	{"error": "bad.tenant","error_description": "error in tenant - tenant validation failed: invalid_tenant"}
400	{"error": "bad.client_id", "error_description": "Missing required property: client_id"}
400	{"error": "bad.connection", "error_description": "Missing required property: connection"}
400	{"error": "bad.connection", "error_description": "Connection does not exist"}
400	{"error": "bad.connection", "error_description": "Connection is disabled"}
400	{"error": "bad.connection", "error_description": "Invalid connection strategy. It must either be a passwordless connection"}
400	{"error": "bad.authParams", "error_description": "error in authParams - invalid type: string (expected object)"}
400	{"error": "bad.request", "error_description": "the following properties are not allowed: "}
400	{"error": "bad.phone_number", "error_description": "Missing required property: phone_number"}
400	{"error": "bad.phone_number", "error_description": "String does not match pattern: ^\\+[0-9]{1,15}$"}
400	{"error": "sms_provider_error", "error_description": " (Code: )"}