Introduction

The Authentication API exposes the identity functionality of Auth0, as well as the supported identity protocols like OpenID Connect, OAuth 2.0, and SAML.

Most users consume this API through our Quickstarts, the Auth0.js library or the Lock widget. However, if you are building all of your authentication UI manually you will have to interact with this API directly.

For each endpoint in this document 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

Login

Social

Examples

GET https://YOUR_AUTH0_DOMAIN/authorize?
  response_type=code|token&
  client_id=YOUR_CLIENT_ID&
  connection=CONNECTION&
  redirect_uri=https://YOUR_APP/callback&
  state=STATE&
  additional-parameter=ADDITIONAL_PARAMETERS
// Script uses auth0.js v8. See Remarks for details.
<script src="http://cdn.auth0.com/js/auth0/8.3.0/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize client
  var webAuth = new auth0.WebAuth({
    domain:       'YOUR_AUTH0_DOMAIN',
    clientID:     'YOUR_CLIENT_ID'
  });
  
  // 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>

GET /authorize

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

NOTE: Social connections only support browser-based (passive) authentication because most social providers don't allow a username and password to be entered into applications that they don't own. Therefore, the user will be redirected to the provider's sign in page.

Request Parameters

Parameter Description
response_type
Required
Use code for server side flows and token for client side flows
client_id
Required
The client_id of your client
connection The name of a social identity provider configured to your client, for example google-oauth2 or facebook. If null, it will redirect to the Auth0 Login Page and show the Login Widget.
redirect_uri
Required
The URL to which Auth0 will redirect the browser after authorization has been granted by the user.
state
Recommended
An opaque value the clients adds to the initial request that the authorization server includes when redirecting the back to the client. This value must be used by the client to prevent CSRF attacks.
additional-parameter Use this to send additional parameters to the provider. For example, access_type=offline (for Google refresh tokens) , display=popup (for Windows Live popup mode).

Test with Authentication API Debugger

Your can use our Authentication API Debugger extension to test this endpoint. In order to do so you need to be logged in and have installed the Authentication API Debugger extension.

Click on Install Debugger to go to the article that explains how (you only have to do this once).

If you have already installed the extension, skip to the Authentication API Debugger.

The link varies according to your tenant's region: US West, Europe Central or Australia.

  1. At the Configuration tab, set the fields Client (select the client 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 Client Settings.

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

Remarks

  • The redirect_uri value must be specified as a valid callback URL under your Client'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.

More Information

Social with Provider's Access Token

Examples

POST https://YOUR_AUTH0_DOMAIN/oauth/access_token
Content-Type: 'application/json'
{
  "client_id": "YOUR_CLIENT_ID",
  "access_token": "ACCESS_TOKEN",
  "connection": "CONNECTION",
  "scope": "SCOPE"
}
curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/oauth/access_token' \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID", "access_token":"ACCESS_TOKEN", "connection":"CONNECTION", "scope":"SCOPE"}'
var url = 'https://' + YOUR_AUTH0_DOMAIN + '/oauth/access_token';
var params = 'client_id=YOUR_CLIENT_ID&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"
}

POST /oauth/access_token

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.

Request Parameters

Parameter Description
client_id
Required
The client_id of your client.
access_token
Required
The social provider's access_token.
connection
Required
The name of an identity provider configured to your app.
scope Use openid to get an id_token, or openid profile email to include user information in the id_token. If null, only an access_token will be returned.

Test with Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below. For more info refer to Using the Auth0 API with our Postman Collections.

Run in Postman

Remarks

  • 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.

Error Codes

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

More Information

Database/AD/LDAP (Passive)

Examples

GET https://YOUR_AUTH0_DOMAIN/authorize?
  response_type=code|token&
  client_id=YOUR_CLIENT_ID&
  connection=CONNECTION&
  redirect_uri=https://YOUR_APP/callback&
  state=STATE
// Script uses auth0.js v8. See Remarks for details.
<script src="http://cdn.auth0.com/js/auth0/8.3.0/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize Client
  var webAuth = new auth0.WebAuth({
    domain:       'YOUR_AUTH0_DOMAIN',
    clientID:     'YOUR_CLIENT_ID'
  });
  
  // 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',
    state: 'YOUR_STATE'
  });
  
  // Redirect to url
  // ...
</script>

GET /authorize

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 login with email and password.

Request Parameters

Parameter Description
response_type
Required
Use code for server side flows and token for client side flows.
client_id
Required
The client_id of your client.
connection The name of the connection configured to your client. If null, it will redirect to the Auth0 Login Page and show the Login Widget using the first database connection.
redirect_uri
Required
The URL to which Auth0 will redirect the browser after authorization has been granted by the user.
state
Recommended
An opaque value the clients adds to the initial request that the authorization server includes when redirecting the back to the client. This value must be used by the client to prevent CSRF attacks.

Test with Authentication API Debugger

Your can use our Authentication API Debugger extension to test this endpoint. In order to do so you need to be logged in and have installed the Authentication API Debugger extension.

Click on Install Debugger to go to the article that explains how (you only have to do this once).

If you have already installed the extension, skip to the Authentication API Debugger.

The link varies according to your tenant's region: US West, Europe Central or Australia.

  1. At the Configuration tab, set the fields Client (select the client 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 Client Settings.

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

Remarks

  • The redirect_uri value must be specified as a valid callback URL under your Client'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.

More Information

Database/AD/LDAP (Active)

Examples

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

// Script uses auth0.js v8. See Remarks for details.
<script src="http://cdn.auth0.com/js/auth0/8.3.0/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize client
  var webAuth = new auth0.WebAuth({
    domain:       'YOUR_AUTH0_DOMAIN',
    clientID:     'YOUR_CLIENT_ID'
  });
  
  // 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>

POST /oauth/ro

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.

Request Parameters

Parameter Description
client_id
Required
The client_id of your client
username
Required
Username/email of the user to login
password
Required
Password of the user to login
connection
Required
The name of the connection to use for login
scope Set to openid to retrieve also an id_token, leave null to get only an access_token
grant_type
Required
Set to password to authenticate using username/password or urn:ietf:params:oauth:grant-type:jwt-bearer to authenticate using an id_token (used to Authenticate users with Touch ID)
device String value. Required when grant_type is urn:ietf:params:oauth:grant-type:jwt-bearer
id_token Used to authenticate using a token instead of username/password, in TouchID scenarios. Required when grant_type is urn:ietf:params:oauth:grant-type:jwt-bearer

Test with Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below. For more info refer to Using the Auth0 API with our Postman Collections.

Run in Postman

Test with Authentication API Debugger

Your can use our Authentication API Debugger extension to test this endpoint. In order to do so you need to be logged in and have installed the Authentication API Debugger extension.

Click on Install Debugger to go to the article that explains how (you only have to do this once).

If you have already installed the extension, skip to the Authentication API Debugger.

The link varies according to your tenant's region: US West, Europe Central or Australia.

  1. At the Configuration tab, set the fields Client (select the client 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 Client Settings.

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

Remarks

  • 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.

Error Codes

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

More Information

Enterprise (SAML and Others)

Examples

GET https://YOUR_AUTH0_DOMAIN/authorize?
  response_type=code|token&
  client_id=YOUR_CLIENT_ID&
  connection=CONNECTION&
  redirect_uri=https://YOUR_APP/callback&
  state=STATE
// Script uses auth0.js v8. See Remarks for details.
<script src="http://cdn.auth0.com/js/auth0/8.3.0/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize client
  var webAuth = new auth0.WebAuth({
    domain:       'YOUR_AUTH0_DOMAIN',
    clientID:     'YOUR_CLIENT_ID'
  });
  
  // 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'
  });
</script>

GET /authorize

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.

Request Parameters

Parameter Description
response_type
Required
Use code for server side flows, token for client side flows.
client_id
Required
The client_id of your client.
connection The name of the connection configured to your client. If null, it will redirect to the Auth0 Login Page and show the Login Widget using the first database connection.
redirect_uri
Required
The URL to which Auth0 will redirect the browser after authorization has been granted by the user.
state
Recommended
An opaque value the clients adds to the initial request that the authorization server includes when redirecting the back to the client. This value must be used by the client to prevent CSRF attacks.

Test with Authentication API Debugger

Your can use our Authentication API Debugger extension to test this endpoint. In order to do so you need to be logged in and have installed the Authentication API Debugger extension.

Click on Install Debugger to go to the article that explains how (you only have to do this once).

If you have already installed the extension, skip to the Authentication API Debugger.

The link varies according to your tenant's region: US West, Europe Central or Australia.

  1. At the Configuration tab, set the fields Client (select the client 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 Client Settings.

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

Remarks

  • 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 Client'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.

More Information

Logout

Examples

GET https://YOUR_AUTH0_DOMAIN/v2/logout?
  client_id=YOUR_CLIENT_ID&
  returnTo=LOGOUT_URL
curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/v2/logout' \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID", "returnTo":"LOGOUT_URL"}'
// Script uses auth0.js v8. See Remarks for details.
<script src="http://cdn.auth0.com/js/auth0/8.3.0/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize client
  var webAuth = new auth0.WebAuth({
    domain:       'YOUR_AUTH0_DOMAIN',
    clientID:     'YOUR_CLIENT_ID'
  });
  
  webAuth.logout({
    returnTo: 'YOUR_LOGOUT_URL',
    client_id: 'YOUR_CLIENT_ID'
  });
</script>

GET /v2/logout

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:

Request Parameters

Parameter Description
returnTo URL to redirect the user after the logout.
client_id The client_id of your client.
federated Add this querystring parameter to the logout URL, to log the user out of their identity provider, as well: https://YOUR_AUTH0_DOMAIN/v2/logout?federated.

Test with Authentication API Debugger

Your can use our Authentication API Debugger extension to test this endpoint. In order to do so you need to be logged in and have installed the Authentication API Debugger extension.

Click on Install Debugger to go to the article that explains how (you only have to do this once).

If you have already installed the extension, skip to the Authentication API Debugger.

The link varies according to your tenant's region: US West, Europe Central or Australia.

  1. At the Configuration tab, set the fields Client (select the client 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 Client Settings.

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

Remarks

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

More Information

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.

Examples

POST https://YOUR_AUTH0_DOMAIN/passwordless/start
Content-Type: 'application/json'
{
  "client_id": "YOUR_CLIENT_ID",
  "connection": "email|sms",
  "email": "EMAIL", //set for connection=email
  "phone_number": "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://YOUR_AUTH0_DOMAIN/passwordless/start' \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID", "connection":"email|sms", "email":"EMAIL", "phone_number":"PHONE_NUMBER", "send":"link|code", "authParams":{"scope": "openid","state": "YOUR_STATE"}}'
// Script uses auth0.js v8. See Remarks for details.
<script src="http://cdn.auth0.com/js/auth0/8.3.0/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize client
  var webAuth = new auth0.WebAuth({
    domain:       'YOUR_AUTH0_DOMAIN',
    clientID:     'YOUR_CLIENT_ID'
  });
  
  // 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>

POST /passwordless/start

You have three options for passwordless authentication:

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

Request Parameters

Parameter Description
client_id
Required
The client_id of your client.
connection
Required
How to send the code/link to the user. Use email to send the code/link using email, or sms to use SMS.
email Set this to the user's email address, when connection=email.
phone_number Set this to the user's phone number, when connection=sms.
send Use link to send a link or code to send a verification code. If null, a link will be sent.
authParams Use this to append or override the link parameters (like scope, redirect_uri, protocol, response_type), when you send a link using email.

Test with Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below. For more info refer to Using the Auth0 API with our Postman Collections.

Run in Postman

Remarks

  • If you sent a verification code, using either email or SMS, after you get the code, you have to authenticate the user using the /oauth/ro endpoint, using email or phone_number as the username, and the verification code as the password.
  • The sample auth0.js script uses the library version 8. If you are using auth0.js version 7, please see this reference guide.

Error Codes

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

More Information

Authenticate User

Examples

POST https://YOUR_AUTH0_DOMAIN/oauth/ro
Content-Type: 'application/json'
{
  "client_id": "YOUR_CLIENT_ID",
  "connection": "email|sms",
  "grant_type": "password",
  "username": "EMAIL|PHONE", //email or phone number
  "password": "VERIFICATION_CODE", //the verification code
  "scope": "SCOPE"
}
curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/oauth/ro' \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID", "connection":"email|sms", "grant_type":"password", "username":"EMAIL|PHONE", "password":"VERIFICATION_CODE", "scope":"SCOPE"}'
// Script uses auth0.js v8. See Remarks for details.
<script src="http://cdn.auth0.com/js/auth0/8.3.0/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize client
  var webAuth = new auth0.WebAuth({
    domain:       'YOUR_AUTH0_DOMAIN',
    clientID:     'YOUR_CLIENT_ID'
  });
  
  // Verify code sent via email
  webAuth.passwordlessVerify({
      connection: 'email',
      email: 'USER_EMAIL',
      verificationCode: 'VERIFICATION_CODE_SENT'
    }, function (err,res) {
      // handle errors or continue
    }
  );

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

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

POST /oauth/ro

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.

Request Parameters

Parameter Description
client_id
Required
The client_id of your client.
connection
Required
Use sms or email (should be the same as POST /passwordless/start)
grant_type
Required
Use password
username
Required
The user's phone number if connection=sms, or the user's email if connection=email.
password
Required
The user's verification code.
scope Use openid to get an id_token, or openid profile email to include also user profile information in the id_token.

Test with Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below. For more info refer to Using the Auth0 API with our Postman Collections.

Run in Postman

Test with Authentication API Debugger

Your can use our Authentication API Debugger extension to test this endpoint. In order to do so you need to be logged in and have installed the Authentication API Debugger extension.

Click on Install Debugger to go to the article that explains how (you only have to do this once).

If you have already installed the extension, skip to the Authentication API Debugger.

The link varies according to your tenant's region: US West, Europe Central or Australia.

  1. At the Configuration tab, set the fields Client (select the client 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 Client 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.

Remarks

  • 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.

Error Codes

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

More Information

Signup

Examples

POST https://YOUR_AUTH0_DOMAIN/dbconnections/signup
Content-Type: 'application/json'
{
  "client_id": "YOUR_CLIENT_ID",
  "email": "EMAIL",
  "password": "PASSWORD",
  "connection": "CONNECTION",
}
curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/dbconnections/signup' \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID", "email":"EMAIL", "password":"PASSWORD", "connection":"CONNECTION"}'
// Script uses auth0.js v8. See Remarks for details.
<script src="http://cdn.auth0.com/js/auth0/8.3.0/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize client
  var webAuth = new auth0.WebAuth({
    domain:       'YOUR_AUTH0_DOMAIN',
    clientID:     'YOUR_CLIENT_ID'
  });
  
  webAuth.signup({ 
    connection: 'CONNECTION', 
    email: 'EMAIL', 
    password: 'PASSWORD'
  }, 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"
}

POST /dbconnections/signup

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.

Request Parameters

Parameter Description
client_id
Required
The client_id of your client.
email
Required
The user's email address.
password
Required
The user's desired password.
connection
Required
The name of the database configured to your client.

Test with Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below. For more info refer to Using the Auth0 API with our Postman Collections.

Run in Postman

Remarks

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

More Information

Change Password

Examples

POST https://YOUR_AUTH0_DOMAIN/dbconnections/change_password
Content-Type: 'application/json'
{
  "client_id": "YOUR_CLIENT_ID",
  "email": "EMAIL",
  "password": "",
  "connection": "CONNECTION",
}
curl --request POST \
  --url https://YOUR_AUTH0_DOMAIN/dbconnections/change_password \
  --header 'content-type: application/json' \
  --data '{"client_id": "YOUR_CLIENT_ID","email": "EMAIL", "password": "", "connection": "CONNECTION"}'
// Script uses auth0.js v8. See Remarks for details.
<script src="http://cdn.auth0.com/js/auth0/8.3.0/auth0.min.js"></script>
<script type="text/javascript">
  var webAuth = new auth0.WebAuth({
    domain:       'YOUR_AUTH0_DOMAIN',
    clientID:     'YOUR_CLIENT_ID'
  });
  
  webAuth.changePassword({
    connection: 'CONNECTION',
    email:   'EMAIL'
  }, function (err, resp) {
    if(err){
      console.log(err.message);
    }else{
      console.log(resp);
    }
  });
</script>

POST /dbconnections/change_password

RESPONSE SAMPLE:

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

Given a user's email address and a connection, Auth0 will send a change password email.

This endpoint only works for database connections.

Request Parameters

Parameter Description
client_id
Required
The client_id of your client.
email
Required
The user's email address.
password The new password. See the next paragraph for the case when a password can be set.
connection
Required
The name of the database connection configured to your client.

Test with Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below. For more info refer to Using the Auth0 API with our Postman Collections.

Run in Postman

Remarks

  • If you are using Lock version 9 and above, do not set the password field or you will receive a password is not allowed error. You can only set the password if you are using Lock version 8.
  • If a password is provided, when the user clicks on the confirm password change link, the new password specified in this POST will be set for this user.
  • If a password is NOT provided, when the user clicks on the password change link they will be redirected to a page asking them for a new password.
  • The sample auth0.js script uses the library version 8. If you are using auth0.js version 7, please see this reference guide.
  • 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.

More Information

User Profile

Get User Info

Examples

GET https://YOUR_AUTH0_DOMAIN/userinfo
Authorization: 'Bearer {ACCESS_TOKEN}'
curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/userinfo' \
  --header 'authorization: Bearer {ACCESS_TOKEN}' \
  --header 'content-type: application/json'
// Script uses auth0.js v8. See Remarks for details.
<script src="http://cdn.auth0.com/js/auth0/8.3.0/auth0.min.js"></script>
<script type="text/javascript">
  // Initialize the Auth0 client
  var webAuth = new auth0.WebAuth({
    domain:       'YOUR_AUTH0_DOMAIN',
    clientID:     'YOUR_CLIENT_ID'
  });
  
  // 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:

{
  "email_verified": false,
  "email": "test.account@userinfo.com",
  "clientID": "q2hnj2iu...",
  "updated_at": "2016-12-05T15:15:40.545Z",
  "name": "test.account@userinfo.com",
  "picture": "https://s.gravatar.com/avatar/dummy.png",
  "user_id": "auth0|58454...",
  "nickname": "test.account",
  "identities": [
    {
      "user_id": "58454...",
      "provider": "auth0",
      "connection": "Username-Password-Authentication",
      "isSocial": false
    }
  ],
  "created_at": "2016-12-05T11:16:59.640Z",
  "sub": "auth0|58454..."
}

GET /userinfo

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.

Request Parameters

Parameter Description
access_token
Required
The Auth0 access_token obtained during login.

Test with Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below. For more info refer to Using the Auth0 API with our Postman Collections.

Run in Postman

Remarks

  • 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. For more information about this, check the Auth0.js v8 Migration Guide.
  • 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.

More Information

Get Token Info

Examples

POST https://YOUR_AUTH0_DOMAIN/tokeninfo
Content-Type: 'application/json'
{
  "id_token": "ID_TOKEN"
}
curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/tokeninfo' \
  --header 'content-type: application/json' \
  --data '{"id_token":""}'
<script src="http://cdn.auth0.com/js/auth0/8.3.0/auth0.min.js"></script>
<script type="text/javascript">
  var webAuth = new auth0.WebAuth({
    domain:       'YOUR_AUTH0_DOMAIN',
    clientID:     'YOUR_CLIENT_ID'
  });
</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..."
}

POST /tokeninfo

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

Request Parameters

Parameter Description
id_token
Required
The id_token to use.

Test with Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below. For more info refer to Using the Auth0 API with our Postman Collections.

Run in Postman

Remarks

  • 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.

More Information

SAML

The SAML protocol is used for 3rd party SaaS applications mostly, like Salesforce and Box. Auth0 supports SP and IDP Initiated Sign On. For more information refer to: SAML.

Accept Request

Examples

GET https://YOUR_AUTH0_DOMAIN/samlp/YOUR_CLIENT_ID?
  connection=CONNECTION
curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/samlp/YOUR_CLIENT_ID' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data '"connection"="CONNECTION"'

GET /samlp/YOUR_CLIENT_ID

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

Optionally, it accepts a connection parameter to login with a specific provider. If no connection is specified, the Auth0 Login Page will be shown.

Request Parameters

Parameter Description
client_id
Required
The client_id of your client.
connection The connection to use.

Test with Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below. For more info refer to Using the Auth0 API with our Postman Collections.

Run in Postman

Remarks

  • 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 the application's callback_URL.

More Information

Get Metadata

Examples

GET https://YOUR_AUTH0_DOMAIN/samlp/metadata/YOUR_CLIENT_ID
curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/samlp/metadata/YOUR_CLIENT_ID'

GET /samlp/metadata/YOUR_CLIENT_ID

This endpoint returns the SAML 2.0 metadata.

Request Parameters

Parameter Description
client_id
Required
The client_id of your client.

Test with Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below. For more info refer to Using the Auth0 API with our Postman Collections.

Run in Postman

More Information

IdP-Initiated SSO Flow

Examples

POST https://YOUR_AUTH0_DOMAIN/login/callback?connection=CONNECTION
Content-Type: 'application/x-www-form-urlencoded'
  SAMLResponse=SAML_RESPONSE
curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/login/callback' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data '"connection":"CONNECTION", "SAMLResponse":"SAML_RESPONSE"'

POST /login/callback

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 querystring. The user will be redirected to the application that is specified in the SAML Provider IdP-Initiated Sign On section.

Request Parameters

Parameter Description
connection
Required
The name of an identity provider configured to your client.
SAMLResponse
Required
An IdP-Initiated Sign On SAML Response.

Test with Authentication API Debugger

Your can use our Authentication API Debugger extension to test this endpoint. In order to do so you need to be logged in and have installed the Authentication API Debugger extension.

Click on Install Debugger to go to the article that explains how (you only have to do this once).

If you have already installed the extension, skip to the Authentication API Debugger.

The link varies according to your tenant's region: US West, Europe Central or Australia.

  1. At the Configuration tab, set the field Client (select the client 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 Client Settings.

  3. At the Other Flows tab, click SAML.

More Information

WS-Federation

Accept Request

Examples

GET https://YOUR_AUTH0_DOMAIN/wsfed/YOUR_CLIENT_ID
curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/wsfed/YOUR_CLIENT_ID'

GET /wsfed/YOUR_CLIENT_ID

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

Request Parameters

Parameter Description
client-id The client-id of your client.
wtrealm Can be used in place of client-id.
whr The name of the connection (used to skip the login page).
wctx Your application's state.
wreply The callback URL.

Test with Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below. For more info refer to Using the Auth0 API with our Postman Collections.

Run in Postman

Test with Authentication API Debugger

Your can use our Authentication API Debugger extension to test this endpoint. In order to do so you need to be logged in and have installed the Authentication API Debugger extension.

Click on Install Debugger to go to the article that explains how (you only have to do this once).

If you have already installed the extension, skip to the Authentication API Debugger.

The link varies according to your tenant's region: US West, Europe Central or Australia.

  1. At the Configuration tab, set the field Client (select the client 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 Client Settings.

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

Remarks

  • The wtrealm parameter must be in one of these formats:
    • urn:clientID (e.g. urn:YOUR_CLIENT_ID)
    • 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.

More Information

Get Metadata

Examples

GET https://YOUR_AUTH0_DOMAIN/wsfed/YOUR_CLIENT_ID/FederationMetadata/2007-06/FederationMetadata.xml
curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/wsfed/YOUR_CLIENT_ID/FederationMetadata/2007-06/FederationMetadata.xml'

GET /wsfed/YOUR_CLIENT_ID/FederationMetadata/2007-06/FederationMetadata.xml

This endpoint returns the WS-Federation metadata.

Test with Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below. For more info refer to Using the Auth0 API with our Postman Collections.

Run in Postman

More Information

Impersonation

Examples

POST https://YOUR_AUTH0_DOMAIN/users/{user_id}/impersonate
Content-Type:   'application/json'
Authorization:  'Bearer {ACCESS_TOKEN}'
{
  protocol: "PROTOCOL",
  impersonator_id: "IMPERSONATOR_ID",
  client_id: "YOUR_CLIENT_ID",
  additionalParameters: [
    "response_type": "code",
    "state": "STATE"
  ]
}
curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/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":"YOUR_CLIENT_ID", "additionalParameters": {"response_type": "code", "state": "STATE"}}'
var url = 'https://' + YOUR_AUTH0_DOMAIN + '/users/' + localStorage.getItem('user_id') + '/impersonate';
var params = 'protocol=PROTOCOL&impersonator_id=IMPERSONATOR_ID&client_id=YOUR_CLIENT_ID';

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...

POST /users/{user_id}/impersonate

Advanced Feature

Impersonation functionality may be disabled by default for your tenant. To check, go to the Users page in the Dashboard, select a user, and see if the Sign in as User button is displayed. If you can't see it, contact support and ask them to enable the feature for your tenant.

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

Request Parameters

Parameter Description
protocol
Required
The protocol to use against the identity provider: oauth2, samlp, wsfed, wsfed-rms.
impersonator_id
Required
The user_id of the impersonator.
client_id
Required
The client_id of the client that is generating the impersonation link.
additionalParameters This is a JSON object. You can use this to set additional parameters, like response_type, scope and state.

Remarks

  • 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.

More Information

Account Linking

Examples

GET https://YOUR_AUTH0_DOMAIN/authorize?
  response_type=code|token&
  client_id=YOUR_CLIENT_ID&
  connection=CONNECTION&
  redirect_uri=https://YOUR_APP/callback&
  access_token=LOGGED_IN_USER_ACCESS_TOKEN

GET /authorize

Deprecation Notice

This endpoint is deprecated for account linking. The POST /api/v2/users/{id}/identities should be used instead. For more information refer to the Migration Notice.

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.

Request Parameters

Parameter Description
response_type
Required
Use code for server side flows, token for client side flows
client_id
Required
The client_id of your client
connection The name of the connection configured to your client. If null, it will redirect to Auth0 Login Page and show the Login Widget using the first database connection.
redirect_uri
Required
The URL to which Auth0 will redirect the browser after authorization has been granted by the user.
access_token
Required
The logged-in user's access token

Remarks

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

More Information

Examples

POST https://YOUR_AUTH0_DOMAIN/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://YOUR_AUTH0_DOMAIN/login/unlink' \
  --header 'content-type: application/json' \
  --data '{"access_token": "LOGGED_IN_USER_ACCESS_TOKEN", "user_id": "LINKED_USER_ID"}'
var url = 'https://' + YOUR_AUTH0_DOMAIN + '/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);

POST /login/unlink

Deprecation Notice

This endpoint is deprecated. The DELETE /api/v2/users/{id}/identities/{provider}/{user_id} should be used instead.

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

Request Parameters

Parameter Description
access_token
Required
The logged-in user's access token
user_id
Required
The logged-in user's user_id

Test with Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below. For more info refer to Using the Auth0 API with our Postman Collections.

Run in Postman

More Information

Delegation

Examples

POST https://YOUR_AUTH0_DOMAIN/delegation
Content-Type: 'application/json'
{
  "client_id": "YOUR_CLIENT_ID",
  "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://YOUR_AUTH0_DOMAIN/delegation' \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID", "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

POST /delegation

Delegated authentication is used when an entity wants to call another entity on behalf of the user. For example, a user logs into an application and then calls an API. The application exchanges the token of the logged in user with a token that is signed with the API secret to call the API.

Given an existing token, this endpoint will generate a new token signed with the target client's secret. This is used to flow the identity of the user from the application to an API or across different APIs that are secured with different secrets.

Request Parameters

Parameter Description
client_id
Required
Τhe client_id of your client
grant_type
Required
Use urn:ietf:params:oauth:grant-type:jwt-bearer
id_token or refresh_token
Required
The existing token of the user.
target The target client_id
scope Use openid or openid profile email
api_type The API to be called.

Test with Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below. For more info refer to Using the Auth0 API with our Postman Collections.

Run in Postman

Test with Authentication API Debugger

Your can use our Authentication API Debugger extension to test this endpoint. In order to do so you need to be logged in and have installed the Authentication API Debugger extension.

Click on Install Debugger to go to the article that explains how (you only have to do this once).

If you have already installed the extension, skip to the Authentication API Debugger.

The link varies according to your tenant's region: US West, Europe Central or Australia.

  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 Client Settings.

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

Remarks

  • 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.

More Information

API Authorization

Authorize Client

To begin an OAuth 2.0 Authorization flow, your Client 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:

On the other hand, the Resource Owner Password Grant and Client Credentials flows do not use this endpoint since there is no user authorization involved. Instead they invoke directly 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?.

Authorization Code Grant

Examples

GET https://YOUR_AUTH0_DOMAIN/authorize?
  audience=API_IDENTIFIER&
  scope=SCOPE&
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://YOUR_APP/callback&
  state=STATE

RESPONSE SAMPLE

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

GET /authorize

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

Request Parameters

Parameter Description
audience
The unique identifier of the target API you want to access.
scope The scopes which you want to request authorization for. These must be separated by a space. You can request any of the standard OIDC scopes about users, such as profile and email, custom claims that must conform to a namespaced format, or any scopes supported by the target API (for example, read:contacts). Include offline_access to get a refresh token.
response_type
Required
Indicates to Auth0 which OAuth 2.0 flow you want to perform. Use code for Authorization Code Grant Flow.
client_id
Required
Your application's Client ID.
state
Recommended
An opaque value the clients adds to the initial request that Auth0 includes when redirecting the back to the client. This value must be used by the client to prevent CSRF attacks.
redirect_uri The URL to which Auth0 will redirect the browser after authorization has been granted by the user.

Test with Authentication API Debugger

Your can use our Authentication API Debugger extension to test this endpoint. In order to do so you need to be logged in and have installed the Authentication API Debugger extension.

Click on Install Debugger to go to the article that explains how (you only have to do this once).

If you have already installed the extension, skip to the Authentication API Debugger.

The link varies according to your tenant's region: US West, Europe Central or Australia.

  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 Client 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.

Remarks

  • In order to improve compatibility for client 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. For example, if you choose the namespace https://foo.com/ and you want to add a custom claim named myclaim, you would name the claim https://foo.com/myclaim, instead of myclaim.
  • 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 Client's Settings.

More Information

Authorization Code Grant (PKCE)

Examples

GET https://YOUR_AUTH0_DOMAIN/authorize?
  audience=API_IDENTIFIER&
  scope=SCOPE&
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://YOUR_APP/callback&
  code_challenge=CODE_CHALLENGE&
  code_challenge_method=S256

RESPONSE SAMPLE

HTTP/1.1 302 Found
Location: https://YOUR_APP/callback?code=AUTHORIZATION_CODE

GET /authorize

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.

Request Parameters

Parameter Description
audience
The unique identifier of the target API you want to access.
scope The scopes which you want to request authorization for. These must be separated by a space. You can request any of the standard OIDC scopes about users, such as profile and email, custom claims that must conform to a namespaced format, or any scopes supported by the target API (for example, read:contacts). Include offline_access to get a refresh token.
response_type
Required
Indicates to Auth0 which OAuth 2.0 Flow you want to perform. Use code for Authorization Code Grant (PKCE) Flow.
client_id
Required
Your application's Client ID.
state
Recommended
An opaque value the clients adds to the initial request that Auth0 includes when redirecting the back to the client. This value must be used by the client to prevent CSRF attacks.
redirect_uri The URL to which Auth0 will redirect the browser after authorization has been granted by the user.
code_challenge_method
Required
Method used to generate the challenge. The PKCE spec defines two methods, S256 and plain, however, Auth0 supports only S256 since the latter is discouraged.
code_challenge
Required
Generated challenge from the code_verifier.

Test with Authentication API Debugger

Your can use our Authentication API Debugger extension to test this endpoint. In order to do so you need to be logged in and have installed the Authentication API Debugger extension.

Click on Install Debugger to go to the article that explains how (you only have to do this once).

If you have already installed the extension, skip to the Authentication API Debugger.

The link varies according to your tenant's region: US West, Europe Central or Australia.

  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 Client 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.

Remarks

  • In order to improve compatibility for client 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. For example, if you choose the namespace https://foo.com/ and you want to add a custom claim named myclaim, you would name the claim https://foo.com/myclaim, instead of myclaim.
  • 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 Client's Settings.

More Information

Implicit Grant

Examples

GET https://YOUR_AUTH0_DOMAIN/authorize?
  audience=API_IDENTIFIER&
  scope=SCOPE&
  response_type=token|id_token token&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://YOUR_APP/callback&
  state=STATE&
  nonce=NONCE

RESPONSE SAMPLE

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

GET /authorize

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

Request Parameters

Parameter Description
audience
The unique identifier of the target API you want to access.
scope The scopes which you want to request authorization for. These must be separated by a space. You can request any of the standard OIDC scopes about users, such as profile and email, custom claims that must conform to a namespaced format, or any scopes supported by the target API (for example, read:contacts).
response_type
Required
This will specify the type of token you will receive at the end of the flow. Use token to get only an access_token, or id_token token to get both an id_token and an access_token.
client_id
Required
Your application's Client ID.
state
Recommended
An opaque value the clients adds to the initial request that Auth0 includes when redirecting the back to the client. This value must be used by the client to prevent CSRF attacks.
redirect_uri The URL to which Auth0 will redirect the browser after authorization has been granted by the user.
nonce
Recommended
A string value which will be included in the ID token response from Auth0, used to prevent token replay attacks. It is required for response_type=id_token token.
connection The name of the connection configured to your client.
prompt To initiate a silent authentication request, use prompt=none.

Test with Authentication API Debugger

Your can use our Authentication API Debugger extension to test this endpoint. In order to do so you need to be logged in and have installed the Authentication API Debugger extension.

Click on Install Debugger to go to the article that explains how (you only have to do this once).

If you have already installed the extension, skip to the Authentication API Debugger.

The link varies according to your tenant's region: US West, Europe Central or Australia.

  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 Client 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.

Remarks

  • The redirect_uri value must be specified as a valid callback URL under your Client'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 client 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. For example, if you choose the namespace https://foo.com/ and you want to add a custom claim named myclaim, you would name the claim https://foo.com/myclaim, instead of myclaim.

More Information

Get Token

Use this endpoint to:

  • Get an access_token in order to call an API. You can, optionally, retrieve an id_token and a refresh_token as well.
  • 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

Examples

POST https://YOUR_AUTH0_DOMAIN/oauth/token
Content-Type: 'application/json'
{
  "grant_type": "authorization_code",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "code": "AUTHORIZATION_CODE",
  "redirect_uri": https://YOUR_APP/callback
}
curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/oauth/token' \
  --header 'content-type: application/json' \
  --data '{"grant_type":"authorization_code","client_id": "YOUR_CLIENT_ID","client_secret": "YOUR_CLIENT_SECRET","code": "AUTHORIZATION_CODE","redirect_uri": "https://YOUR_APP/callback"}'
var request = require("request");

var options = { method: 'POST',
  url: 'https://YOUR_AUTH0_DOMAIN/oauth/token',
  headers: { 'content-type': 'application/json' },
  body:
   { grant_type: 'authorization_code',
     client_id: 'YOUR_CLIENT_ID',
     client_secret: 'YOUR_CLIENT_SECRET',
     code: 'AUTHORIZATION_CODE',
     redirect_uri: 'https://YOUR_APP/callback' },
  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
{
  "access_token":"eyJz93a...k4laUWw",
  "refresh_token":"GEbRxBN...edjnXbL",
  "id_token":"eyJ0XAi...4faeEoQ",
  "token_type":"Bearer",
  "expires_in":86400
}

POST /oauth/token

This is the OAuth 2.0 grant that regular web apps utilize in order to access an API. Use this endpoint to exchange an Authorization Code for a Token.

Request Parameters

Parameter Description
grant_type
Required
Denotes the flow you are using. For Authorization Code use authorization_code.
client_id
Required
Your application's Client ID.
client_secret
Required
Your application's Client Secret.
code
Required
The Authorization Code received from the initial /authorize call.
redirect_uri This is required only if it was set at the GET /authorize endpoint. The values must match.

Test with Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below. For more info refer to Using the Auth0 API with our Postman Collections.

Run in Postman

Test with Authentication API Debugger

Your can use our Authentication API Debugger extension to test this endpoint. In order to do so you need to be logged in and have installed the Authentication API Debugger extension.

Click on Install Debugger to go to the article that explains how (you only have to do this once).

If you have already installed the extension, skip to the Authentication API Debugger.

The link varies according to your tenant's region: US West, Europe Central or Australia.

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 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 Client Settings.

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

More Information

Authorization Code (PKCE)

Examples

POST https://YOUR_AUTH0_DOMAIN/oauth/token
Content-Type: 'application/json'
{
  "grant_type": "authorization_code",
  "client_id": "YOUR_CLIENT_ID",
  "code_verifier": "CODE_VERIFIER",
  "code": "AUTHORIZATION_CODE",
  "redirect_uri": "com.myclientapp://myclientapp.com/callback"
}
curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/oauth/token' \
  --header 'content-type: application/json' \
  --data '{"grant_type":"authorization_code","client_id": "YOUR_CLIENT_ID","code_verifier": "CODE_VERIFIER","code": "AUTHORIZATION_CODE","redirect_uri": "com.myclientapp://myclientapp.com/callback"}'
var request = require("request");

var options = { method: 'POST',
  url: 'https://YOUR_AUTH0_DOMAIN/oauth/token',
  headers: { 'content-type': 'application/json' },
  body: '{"grant_type":"authorization_code","client_id": "YOUR_CLIENT_ID","code_verifier": "CODE_VERIFIER","code": "AUTHORIZATION_CODE","redirect_uri": "com.myclientapp://myclientapp.com/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
}

POST /oauth/token

This is the OAuth 2.0 grant that mobile apps utilize in order to access an API. Use this endpoint to exchange an Authorization Code for a Token.

Request Parameters

Parameter Description
grant_type
Required
Denotes the flow you are using. For Authorization Code (PKCE) use authorization_code.
client_id
Required
Your application's Client ID.
code
Required
The Authorization Code received from the initial /authorize call.
code_verifier
Required
Cryptographically random key that was used to generate the code_challenge passed to /authorize.
redirect_uri This is required only if it was set at the GET /authorize endpoint. The values must match.

Test with Authentication API Debugger

Your can use our Authentication API Debugger extension to test this endpoint. In order to do so you need to be logged in and have installed the Authentication API Debugger extension.

Click on Install Debugger to go to the article that explains how (you only have to do this once).

If you have already installed the extension, skip to the Authentication API Debugger.

The link varies according to your tenant's region: US West, Europe Central or Australia.

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 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 Client 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.

More Information

Client Credentials

Examples

POST https://YOUR_AUTH0_DOMAIN/oauth/token
Content-Type: 'application/json'
{
  audience: "API_IDENTIFIER",
  grant_type: "client_credentials",
  client_id: "YOUR_CLIENT_ID",
  client_secret: "YOUR_CLIENT_SECRET"
}
curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/oauth/token' \
  --header 'content-type: application/json' \
  --data '{"audience":"API_IDENTIFIER", "grant_type":"client_credentials", "client_id":"YOUR_CLIENT_ID", "client_secret":"YOUR_CLIENT_SECRET"}'
var request = require("request");

var options = { method: 'POST',
  url: 'https://YOUR_AUTH0_DOMAIN/oauth/token',
  headers: { 'content-type': 'application/json' },
  body:
   { client_id: 'YOUR_CLIENT_ID',
     client_secret: 'YOUR_CLIENT_SECRET',
     audience: 'API_IDENTIFIER',
     grant_type: 'client_credentials' },
  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
{
  "access_token":"eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "expires_in":86400
}

POST /oauth/token

This is the OAuth 2.0 grant that server processes utilize in order to access an API. Use this endpoint to directly request an access_token by using the Client Credentials (a Client Id and a Client Secret).

Request Parameters

Parameter Description
grant_type
Required
Denotes the flow you are using. For Client Credentials use client_credentials.
client_id
Required
Your application's Client ID.
client_secret
Required
Your application's Client Secret.
audience
Required
The unique identifier of the target API you want to access.

Test with Authentication API Debugger

Your can use our Authentication API Debugger extension to test this endpoint. In order to do so you need to be logged in and have installed the Authentication API Debugger extension.

Click on Install Debugger to go to the article that explains how (you only have to do this once).

If you have already installed the extension, skip to the Authentication API Debugger.

The link varies according to your tenant's region: US West, Europe Central or Australia.

  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 Client Settings.

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

More Information

Resource Owner Password

Examples

POST https://YOUR_AUTH0_DOMAIN/oauth/token
Content-Type: 'application/json'
{
  "grant_type": "password",
  "username": "USERNAME",
  "password": "PASSWORD",
  "audience": "API_IDENTIFIER",
  "scope": "SCOPE",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}
curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/oauth/token' \
  --header 'content-type: application/json' \
  --data '{"grant_type":"password", "username":"USERNAME", "password":"PASSWORD", "audience":"API_IDENTIFIER", "scope":"SCOPE", "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET"
 }'
var request = require("request");

var options = { method: 'POST',
  url: 'https://YOUR_AUTH0_DOMAIN/oauth/token',
  headers: { 'content-type': 'application/json' },
  body:
   { grant_type: 'password',
     username: 'USERNAME',
     password: 'PASSWORD',
     audience: 'API_IDENTIFIER',
     scope: 'SCOPE',
     client_id: 'YOUR_CLIENT_ID',
     client_secret: 'YOUR_CLIENT_SECRET' },
  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
{
  "access_token":"eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "expires_in":86400
}

POST /oauth/token

This is the OAuth 2.0 grant that highly trusted apps utilize in order 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 later on sent to the client and Auth0. It is therefore imperative that the client is absolutely trusted with this information.

Request Parameters

Parameter Description
grant_type
Required
Denotes the flow you are using. For Resource Owner Password use password. To add realm support use http://auth0.com/oauth/grant-type/password-realm.
client_id
Required
Your application's Client ID.
client_secret Your application's Client Secret. Required when the Token Endpoint Authentication Method field at your Client Settings is Post or Basic. Do not set this parameter if your client is not highly trusted (for example, SPA).
audience The unique identifier of the target API you want to access.
username
Required
Resource Owner's identifier.
password
Required
Resource Owner's secret.
scope String value of the different scopes the client is asking for. Multiple scopes are separated with whitespace.
realm String value of the realm the user belongs. Set this if you want to add realm support at this grant. For more information on what realms are refer to Realm Support.

Test with Authentication API Debugger

Your can use our Authentication API Debugger extension to test this endpoint. In order to do so you need to be logged in and have installed the Authentication API Debugger extension.

Click on Install Debugger to go to the article that explains how (you only have to do this once).

If you have already installed the extension, skip to the Authentication API Debugger.

The link varies according to your tenant's region: US West, Europe Central or Australia.

  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 Client Settings.

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

Remarks

  • The scopes issued to the client 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 client in this grant. You can customize the scopes returned in a rule. For more information, refer to Calling APIs from Highly Trusted Clients.
  • 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.

More Information

Resource Owner

Examples

POST https://YOUR_AUTH0_DOMAIN/oauth/ro
Content-Type: 'application/json'
{
  "client_id": "YOUR_CLIENT_ID",
  "connection": "CONNECTION",
  "grant_type": "password",
  "username": "USERNAME",
  "password": "PASSWORD",
  "scope": "SCOPE",
  "id_token": "ID_TOKEN",
  "device": "DEVICE"
}
curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/oauth/ro' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{ "client_id": "YOUR_CLIENT_ID", "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://YOUR_AUTH0_DOMAIN/oauth/ro',
  headers: { 'content-type': 'application/json', 'accept': 'application/json' },
  body:
   { connection: 'CONNECTION',
     grant_type: 'PASSWORD',
     username: 'USERNAME',
     client_id: 'YOUR_CLIENT_ID',
     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"
}

POST /oauth/ro

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.

Request Parameters

Parameter Description
client_id
Required
Your application's Client ID.
connection
Required
The name of the connection configured to your client
grant_type
Required
Use the value password
username
Required
The user's username
password
Required
The user's password
scope Use openid to get an id_token, openid profile email to get an id_token and the user profile, or openid offline_access to get an id_token and a refresh_token.
id_token Used to authenticate using a token instead of username/password, in TouchID scenarios.
device You should set this to a string, if you are requesting a refresh token (scope=offline_access).

Test with Authentication API Debugger

Your can use our Authentication API Debugger extension to test this endpoint. In order to do so you need to be logged in and have installed the Authentication API Debugger extension.

Click on Install Debugger to go to the article that explains how (you only have to do this once).

If you have already installed the extension, skip to the Authentication API Debugger.

The link varies according to your tenant's region: US West, Europe Central or Australia.

  1. At the Configuration tab, set the Client field to the client 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 Client Settings.

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

Remarks

  • 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.

Error Codes

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

More Information

Errors

Standard Error Responses

The Authentication API may return the following HTTP Status Codes:

Error Code Description
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
429 Too Many Requests
500 Internal Server Error
503 Service Unavailable

POST /oauth/access_token

HTTP 400

JSON Description
{"error": "invalid_request", "error_description": "the connection was disabled"} The connection is not active or not enabled for your client_id.
{"error": "invalid_request", "error_description": "the connection was not found"} Invalid connection name.
{"error": "invalid_request", "error_description": "missing client_id parameter"} The client_id value is null.
{"error": "invalid_request", "error_description": "missing access_token parameter"} The access_token value is null.
{"error": "invalid_request", "error_description": "missing connection parameter"} The connection value is null.

HTTP 401

JSON Description
{"error": "invalid_request", "error_description": "invalid access_token: invalid_token"} The access_token is invalid or does not contain the scope you set.

HTTP 403

JSON Description
{"error": "unauthorized_client", "error_description": "invalid client"} The client_id is invalid.

POST /oauth/ro

Grant type: jwt-bearer

HTTP 400

JSON Description
{"error": "invalid_request", "error_description": "missing device parameter"} Missing Device. You need to provide a device name for the caller device (like a browser, app, etc).
{"error": "invalid_request", "error_description": "missing id_token parameter"} Missing id_token. For this grant type you need to provide a JWT id token.
{"error": "invalid_grant", "error_description": "..."} Errors related to an invalid id_token or user.

Grant type: password

HTTP 400

JSON Description
{"error": "invalid_request", "error_description": "missing username parameter"} Missing username parameter in the request.
{"error": "invalid_request", "error_description": "missing password parameter"} Missing password parameter in the request.
{"error": "invalid_request", "error_description": "missing connection parameter"} Missing connection parameter in the request.
{"error": "invalid_request", "error_description": "scope parameter must be a string"} Incorrect scope formatting. Each scope must be separated by whitespace.
{"error": "invalid_request", "error_description": "specified strategy does not support requested operation"} The connection/provider does not implement username/password authentication.

HTTP 401

JSON Description
{"error": "invalid_user_password", "error_description": "Wrong email or password."} Wrong username or password (this can vary depending on the identity provider).
{"error": "unauthorized", "error_description": "user is blocked"} The user is blocked.
{ "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."} Another site had a security breach and your password has been leaked.

HTTP 429

JSON Description
{"error": "too_many_attempts", "error_description": "..."} Some anomaly detections will return this error.
{"error": "too_many_logins", "error_description": "..."} Some anomaly detections will return this error.

All grant types

HTTP 400

JSON Description
{"error": "invalid_request", "error_description": "missing client_id parameter"} Missing client_id parameter in the request.
{"error": "invalid_request", "error_description": "the connection was not found"} Provided connection was not found.
{"error": "invalid_request", "error_description": "the connection was disabled"} Provided connection is disabled. Check the connection in the dashboard, you may have turned it off for the provided client_id.
{"error": "invalid_request", "error_description": "The connection is not yet configured..."} The connection is not properly configured with custom scripts.
{"error": "invalid_request", "error_description": "the connection was not found for tenant..."} The connection does not belong to the tenant. Check your base url.
{"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.

HTTP 403

JSON Description
{"error": "unauthorized_client", "error_description": "invalid client"} Provided client_id is not valid.
{"error": "access_denied", "error_description": "..."} Validation of specific points raised an access issue.

POST /passwordless/start

HTTP 400

JSON Description
{"error": "bad.tenant", "error\_description": "error in tenant - tenant validation failed: invalid\_tenant"} Invalid tenant
{"error": "bad.client\_id", "error\_description": "Missing required property: client_id"} Missing client_id
{"error": "bad.connection", "error_description": "Missing required property: connection"} Missing connection
{"error": "bad.connection", "error_description": "Connection does not exist"} Connection does not exist
{"error": "bad.connection", "error_description": "Connection is disabled"} Disabled connection
{"error": "bad.connection", "error_description": "Invalid connection strategy. It must either be a passwordless connection"} Invalid connection
{"error": "bad.authParams", "error_description": "error in authParams - invalid type: string (expected object)"} Invalid authParams
{"error": "bad.request", "error\_description": "the following properties are not allowed: <INVALID_PARAMETER_VALUE>"} Invalid paramaters
{"error": "bad.phone\_number", "error\_description": "Missing required property: phone_number"} Missing phone_number
{"error": "bad.phone\_number", "error_description": "String does not match pattern: ^\\+[0-9]{1,15}$"} Invalid phone_number format
{"error": "sms\_provider\_error", "error\_description": "<SPECIFIC_PROVIDER_MESSAGE> (Code: <SPECIFIC_PROVIDER_CODE>)"} SMS Provider errors