Join Developer Day on Sep 24, 2024, to unleash the power of Auth0.
Reserve your spotJoin Developer Day on Sep 24, 2024
Reserve your spotThe 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, FAPI 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:
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:
cname-api-key
header.client-certificate
header.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¶m=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:
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.
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.
On 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).
Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.
At the OAuth2 / OIDC tab, select OAuth2 / OIDC Login.
Configure other endpoints with the following options:
connection=sms
, or the user's email if connection=email
, and Password to the user's verification code. Click Resource Owner Endpoint.Configure authentication flows with the following options:
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.
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>
You can connect your Auth0 service to a social identity provider and allow your users to log in to your application via Facebook, Google, Apple, or other supported providers. To learn more about supported providers, visit Marketplace.
To authenticate users with a social provider, make a GET
call to the /authorize
endpoint. It will return a 302
redirect to the social provider specified in the connection
parameter.
Parameter | Description |
---|---|
response_type Required |
Specifies the token type. Use code for server side flows and token for application side flows |
client_id Required |
The client_id of your application |
connection |
The name of a social identity provider configured to your application, 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. Specify the redirect_uri under your Application's Settings. |
state Recommended |
An opaque value the applications adds to the initial request that the authorization server includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks. |
ADDITIONAL_PARAMETERS |
Append any additional parameter to the end of your request, and it will be sent to the provider. For example, access_type=offline (for Google Refresh Tokens) , display=popup (for Windows Live popup mode). |
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.
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 the Auth0 user store or your own database to store and manage username and password credentials. If you have your own user database, you can use it as an identity provider in Auth0 to authenticate users. When you make a GET
call to the /authorize
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.
Parameter | Description |
---|---|
response_type Required |
Specifies the token type. Use code for server side flows and token for application side flows. |
client_id Required |
The client_id of your application. |
connection |
The name of the connection configured to your application. 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. Specify the redirect_uri under your Application's Settings. |
scope Recommended |
OIDC scopes and custom API scopes. For example: openid read:timesheets . Include offline_access to get a Refresh Token. |
state Recommended |
An opaque value the applications adds to the initial request that the authorization server includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks. |
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.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>
You can connect your Auth0 service to an enterprise identity provider and allow your users to log in to your application via Microsoft Azure Active Directory, Google Workspace, Okta Workforce, or other supported providers. To learn more about supported providers, visit Auth0 Marketplace.
Make a GET
call to the /authorize
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.
Parameter | Description |
---|---|
response_type Required |
Specifies the token type. Use code for server side flows, token for application side flows. |
client_id Required |
The client_id of your application. |
connection |
The name of the connection configured to your application. 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. Specify the redirect_uri under your Application's Settings. |
state Recommended |
An opaque value the applications adds to the initial request that the authorization server includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks. |
connection
is specified, it will redirect to the Login Page and show the Login Widget.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.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:
client_id
parameter is included, the returnTo
URL must be listed in the Allowed Logout URLs
set at the application level. To learn more, read Log Users Out of Applications.client_id
parameter is NOT included, the returnTo
URL must be listed in the Allowed Logout URLs
set at the tenant level. To learn more, read Log Users Out of Auth0.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. To learn more, read Log Users Out of Applications.Parameter | Description |
---|---|
returnTo |
URL to redirect the user after the logout. |
client_id |
The client_id of your application. |
federated |
Add this query string parameter to the logout URL, to log the user out of their identity provider, as well: https://{yourDomain}/v2/logout?federated . |
federated
query string parameter.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:
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
.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:
client_id
parameter is included, the post_logout_redirect_uri
URL must be listed in the Allowed Logout URLs
set at the application level.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.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 Auth0 Dashboard.To learn more, read Log Users Out of Auth0 with OIDC Endpoint.
Parameter | Description |
---|---|
id_token_hint (Recommended) |
Previously issued ID Token for the user. This is used to indicate which user to log out. |
logout_hint (Optional) |
Optional sid (session ID) value to indicate which user to log out. Should be provided when id_token_hint is not available. |
post_logout_redirect_uri (Optional) |
URL to redirect the user after the logout. |
client_id (Optional) |
The client_id of your application. |
federated (Optional) |
Add this query string parameter to log the user out of their identity provider: https://YOUR_DOMAIN/oidc/logout?federated . |
state (Optional) |
An opaque value the applications adds to the initial request that the authorization server includes when redirecting the back to thepost_logout_redirect_uri . |
ui_locales (Optional) |
Space-delimited list of locales used to constrain the language list for the request. The first locale on the list must match the enabled locale in your tenant |
federated
query string parameter with social identity providers.id_token_hint
and logout_hint
, the logout_hint
value must match the sid
claim from the id_token_hint.id_token_hint
and client_id
, the client_id
value must match the aud
claim from the id_token_hint
.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.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
.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.
Parameter | Description |
---|---|
CLIENT_ID |
Client ID of your application configured with the SAML2 Web App addon. |
SAML_LOGOUT_REQUEST |
SAML <LogoutRequest> message. |
<LogoutRequest>
message. To learn more, read Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0 on Oasis.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:
Parameter | Description |
---|---|
client_id Required |
The client_id of your application. |
client_assertion |
A JWT containing containing a signed assertion with your applications credentials. Required when Private Key JWT is your application authentication method. |
client_assertion_type |
Use the value urn:ietf:params:oauth:client-assertion-type:jwt-bearer . Required when Private Key JWT is the application authentication method. |
client_secret |
The client_secret of your application. Required when the Token Endpoint Authentication Method field at your Application Settings is Post or Basic . Specifically required for Regular Web Applications only. |
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. |
email
or phone_number
as the username
, and the verification code as the password
.For the complete error code reference for this endpoint refer to Errors > POST /passwordless/start.
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.
Parameter | Description |
---|---|
grant_type Required |
It should be http://auth0.com/oauth/grant-type/passwordless/otp . |
client_id Required |
The client_id of your application. |
client_assertion |
A JWT containing a signed assertion with your application credentials. Required when Private Key JWT is your application authentication method. |
client_assertion_type |
The value is urn:ietf:params:oauth:client-assertion-type:jwt-bearer . Required when Private Key JWT is the application authentication method. |
client_secret |
The client_secret of your application. Required** when the Token Endpoint Authentication Method field at your Application Settings is Post or Basic . Specifically required for Regular Web Applications only. |
username Required |
The user's phone number if realm=sms , or the user's email if realm=email . |
realm Required |
Use sms or email (should be the same as POST /passwordless/start) |
otp Required |
The user's verification code. |
audience |
API Identifier of the API for which you want to get an Access Token. |
scope |
Use openid to get an ID Token, or openid profile email to also include user profile information in the ID Token. |
redirect_uri Required |
A callback URL that has been registered with your application's Allowed Callback URLs. |
For the complete error code reference for this endpoint refer to Standard Error Responses.
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.
Parameter | Description |
---|---|
client_id Required |
The client_id of your application. |
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. |
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
.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 /passwordless/verify.
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 creates a new user.
This endpoint only works for database connections.
Parameter | Description |
---|---|
client_id |
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. |
username |
The user's username. Only valid if the connection requires a username. |
given_name |
The user's given name(s). |
family_name |
The user's family name(s). |
name |
The user's full name. |
nickname |
The user's nickname. |
picture |
A URI pointing to the user's picture. |
user_metadata |
The user metadata to be associated with the user. If set, the field must be an object containing no more than ten properties. Property names can have a maximum of 100 characters, and property values must be strings of no more than 500 characters. |
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.
Parameter | Description |
---|---|
client_id |
The client_id of your client. |
email Required |
The user's email address. |
connection Required |
The name of the database connection configured to your client. |
organization |
The organization_id of the Organization associated with the user. |
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.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 scope of openid profile email
.
Parameter | Description |
---|---|
access_token Required |
The Auth0 Access Token obtained during login. |
parseHash
method, requires that your tokens are signed with RS256
, rather than HS256
.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.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.Email
claim returns a snapshot of the email at the time of loginemail
) return the latest value (unless the value comes from an external IdP)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
)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.
To learn more, read:
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.
Parameter | Description |
---|---|
mfa_token Required |
The token received from mfa_required error. |
client_id Required |
Your application's Client ID. |
client_assertion |
A JWT containing a signed assertion with your application credentials. Required when Private Key JWT is your application authentication method. |
client_assertion_type |
The value is urn:ietf:params:oauth:client-assertion-type:jwt-bearer . Required when Private Key JWT is the application authentication method. |
client_secret |
Your application's Client Secret. Required when the Token Endpoint Authentication Method field at your Application Settings is Post or Basic . |
challenge_type |
A whitespace-separated list of the challenges types accepted by your application. Accepted challenge types are oob or otp . Excluding this parameter means that your client application accepts all supported challenge types. |
authenticator_id |
The ID of the authenticator to challenge. You can get the ID by querying the list of available authenticators for the user as explained on List authenticators below. |
unsupported_challenge_type
error is returned if your application does not support any of the challenge types the user has enrolled with.unsupported_challenge_type
error is returned if the user is not enrolled.association_required
error, indicating the user needs to enroll to use MFA. Read Add an authenticator below on how to proceed.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.
Parameter | Description |
---|---|
grant_type Required |
Denotes the flow you are using. For OTP MFA use http://auth0.com/oauth/grant-type/mfa-otp . |
client_id |
Your application's Client ID. |
client_assertion |
A JWT containing a signed assertion with your application credentials. Required when Private Key JWT is your application authentication method. |
client_assertion_type |
The value is urn:ietf:params:oauth:client-assertion-type:jwt-bearer . Required when Private Key JWT is the application authentication method. |
client_secret |
Your application's Client Secret. Required when the Token Endpoint Authentication Method field at your Application Settings is Post or Basic . |
mfa_token Required |
The mfa_token you received from mfa_required error. |
otp Required |
OTP Code provided by the user. |
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:
password
or http://auth0.com/oauth/grant-type/password-realm
grant types.invalid_grant
error, meaning that the challenge was rejected by the user. At this point you should stop polling, as this response is final.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.
Parameter | Description |
---|---|
grant_type Required |
Denotes the flow you are using. For OTP MFA, use http://auth0.com/oauth/grant-type/mfa-oob . |
client_id Required |
Your application's Client ID. |
client_assertion |
A JWT containing a signed assertion with your application credentials. Required when Private Key JWT is your application authentication method. |
client_assertion_type |
The value is urn:ietf:params:oauth:client-assertion-type:jwt-bearer . Required when Private Key JWT is the application authentication method. |
client_secret |
Your application's Client Secret. Required when the Token Endpoint Authentication Method field at your Application Settings is Post or Basic . |
mfa_token Required |
The mfa_token you received from mfa_required error. |
oob_code Required |
The oob code received from the challenge request. |
binding_code |
A code used to bind the side channel (used to deliver the challenge) with the main channel you are using to authenticate. This is usually an OTP-like code delivered as part of the challenge message. |
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.
Parameter | Description |
---|---|
grant_type Required |
Denotes the flow you are using. For recovery code use http://auth0.com/oauth/grant-type/mfa-recovery-code . |
client_id Required |
Your application's Client ID. |
client_assertion |
A JWT containing a signed assertion with your application credentials. Required when Private Key JWT is your application authentication method. |
client_assertion_type |
The value is urn:ietf:params:oauth:client-assertion-type:jwt-bearer . Required when Private Key JWT is the application authentication method. |
client_secret |
Your application's Client Secret. Required when the Token Endpoint Authentication Method field at your Application Settings is Post or Basic . |
mfa_token Required |
The mfa_token you received from mfa_required error. |
recovery_code Required |
Recovery code provided by the end-user. |
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/
Parameter | Description |
---|---|
client_id Required |
Your application's Client ID. |
client_assertion |
A JWT containing a signed assertion with your application credentials. Required when Private Key JWT is your application authentication method. |
client_assertion_type |
The value is urn:ietf:params:oauth:client-assertion-type:jwt-bearer . Required when Private Key JWT is the application authentication method. |
client_secret |
Your application's Client Secret. Required when the Token Endpoint Authentication Method field in your Application Settings is Post or Basic . |
authenticator_types Required |
The type of authenticators supported by the client. Value is an array with values "otp" or "oob" . |
oob_channels |
The type of OOB channels supported by the client. An array with values "auth0" , "sms" , "voice" . Required if authenticator_types include oob . |
phone_number |
The phone number to use for SMS or Voice. Required if oob_channels includes sms or voice . |
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/
Parameter | Description |
---|---|
ACCESS_TOKEN Required |
The Access Token obtained during login. |
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/
Parameter | Description |
---|---|
ACCESS_TOKEN Required |
The Access Token obtained during login. |
AUTHENTICATOR_ID Required |
The ID of the authenticator to delete. |
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.
Parameter | Description |
---|---|
client_id Required |
Client ID of your application. |
connection |
Connection to use during login. |
organization |
Organization ID, if authenticating in the context of an organization. |
AssertionConsumerServiceURL
will be used to POST
back the assertion. It must match one of the application's callback_URLs
.GET https://{yourDomain}/samlp/metadata/{yourClientId}
curl --request GET \
--url 'https://{yourDomain}/samlp/metadata/{yourClientId}'
This endpoint returns the SAML 2.0 metadata.
Parameter | Description |
---|---|
client_id Required |
The client_id of your application. |
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.
Parameter | Description |
---|---|
connection Required |
The name of an identity provider configured to your application. |
SAMLResponse Required |
An IdP-Initiated Sign On SAML Response. |
GET https://{yourDomain}/wsfed/{yourClientId}
curl --request GET \
--url 'https://{yourDomain}/wsfed/{yourClientId}'
This endpoint accepts a WS-Federation request to initiate a login.
Parameter | Description |
---|---|
client-id |
The client-id of your application. |
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. |
wtrealm
parameter must be in one of these formats:
urn:clientID
(for example, urn:{yourClientId})client.clientAliases
array is used for look-up. This can only be set with the /api/v2/clients Management API.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.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.
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.
Parameter | Description |
---|---|
client_name |
The name of the Dynamic Client to be created. It is recommended to provide a value but if it is omitted, the default name "My App" will be used. |
redirect_uris Required |
An array of URLs that Auth0 will deem valid to call at the end of an Authentication flow. |
token_endpoint_auth_method |
Default value is client_secret_post . Use token_endpoint_auth_method: none in the request payload if creating a SPA. |
API Authorization
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:
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?.
For token-based authentication, use the oauth/token
endpoint to get an access token for your application to make authenticated calls to a secure API. Optionally, you can also retrieve an ID Token and a Refresh Token. ID Tokens contains user information in the form of scopes you application can extract to provide a better user experience. Refresh Tokens allow your application to request a new access token once the current token expires without interruping the user experience. To learn more, read ID Tokens and Refresh Tokens.
Note that the only OAuth 2.0 flows that can retrieve a Refresh Token are:
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.
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 OpenID Connect (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 use. Use code for Authorization Code Grant Flow. |
client_id Required |
Your application's ID. |
state Recommended |
An opaque value the application adds to the initial request that Auth0 includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks. |
redirect_uri |
The URL to which Auth0 will redirect the browser after authorization has been granted by the user. |
connection |
The name of the connection configured to your application. |
prompt |
To initiate a silent authentication request, use prompt=none (To learn more, read the Remarks). |
organization |
ID of the organization to use when authenticating a user. When not provided, if your application is configured to Display Organization Prompt, the user will be able to enter the organization name when authenticating. |
invitation |
Ticket ID of the organization invitation. When inviting a member to an Organization, your application should handle invitation acceptance by forwarding the invitation and organization key-value pairs when the user accepts the invitation. |
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.
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 from /authorize must match the value you set at /oauth/token . |
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.
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 OpenID Connect (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 client adds to the initial request that Auth0 includes when redirecting 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 . |
connection |
The name of the connection configured to your application. |
prompt |
To initiate a silent authentication request, use prompt=none (To learn more, read the Remarks). |
organization |
ID of the organization to use when authenticating a user. When not provided, if your application is configured to Display Organization Prompt, the user will be able to enter the organization name when authenticating. |
invitation |
Ticket ID of the organization invitation. When inviting a member to an Organization, your application should handle invitation acceptance by forwarding the invitation and organization key-value pairs when the user accepts the invitation. |
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.
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 from /authorize must match the value you set at /oauth/token . |
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.redirect_uri
value must be specified as a valid callback URL under your Application's Settings.POST {yourDomain}/oauth/par
Content-Type: 'application/x-www-form-urlencoded'
audience={https://yourApi/}&
response_type=code|code id_token&
client_id={yourClientId}&
redirect_uri={https://yourApp/callback}&
state=STATE&
scope=openid|profile|email&
code_challenge=CODE_CHALLENGE&
code_challenge_method=S256&
nonce=NONCE&
connection=CONNECTION&
prompt=login|consent|none&
organisation=ORGANIZATION
var request = require("request");
var options = { method: 'POST',
url: 'https://{yourDomain}/oauth/par,
headers: { 'content-type': 'application/x-www-form-urlencoded' },
form: {
audience: '{https://yourApi/}',
response_type: 'code|code id_token',
client_id: '{yourClientId}',
redirect_uri: '{https://yourApp/callback}',
state: 'STATE',
scope: 'openid|profile|email',
authorization_details: JSON.stringify([{ type: 'my_type' }]),
code_challenge: 'CODE_CHALLENGE',
code_challenge_method: 'S256',
nonce: 'NONCE',
connection: 'CONNECTION',
prompt: 'login|consent|none'
organisation: 'ORGANIZATION'
}
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});
curl --request POST \
--url 'https://{yourDomain}/oauth/par' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'audience={https://yourApi/}response_type=code|code id_token&client_id={yourClientId}&redirect_uri={https://yourApp/callback}&state=STATE&scope=openid|profile|email&authorization_details='[{"type":"my_type"}]'
&code_challenge=CODE_CHALLENGE&code_challenge_method=S256&nonce=NONCE&connection=CONNECTION&prompt=login|consent|none&organisation=ORGANIZATION'
RESPONSE SAMPLE:
/**
If the request is successful, `/oauth/par` responds with a `JSON` object containing the `request_uri` property, which can be used at the authorization endpoint, and the `expires_in` value, which indicates the number of seconds the `request_uri` is valid.
*/
HTTP/1.1 201 Created
Content-Type: application/json
{
"request_uri":
"urn:ietf:params:oauth:request_uri:6esc_11ACC5bwc014ltc14eY22c",
"expires_in": 30
}
Authorization Code Flow with Pushed Authorization Requests (PAR) uses the /oauth/par
endpoint to allow applications to send the authorization parameters usually sent in a GET
request to /authorize
. PAR uses a POST method from the backend to keep parameter values secure. The /oauth/par
endpoint accepts all authorization parameters which can be proivided to /authorize
. Assuming the call to the /oauth/par
endpoint is valid, Auth0 will respond with a redirect_uri
value that can be used as a parameter for the /authorize
endpoint.
Assuming the call to the /oauth/par
endpoint is valid, Auth0 will respond with a redirect_uri
value also used as a parameter for the /authorize
endpoint. To learn more about configuring PAR, read Configure Pushed Authorization Requests (PAR).
Parameter | Description |
---|---|
authorization_details |
Requested permissions for each resource. Similar to scopes. To learn more, read RAR reference documention. |
audience |
The unique identifier of the target API you want to access. |
response_type Required |
Specifies the token type. We recommend you use code to request an authorization code, or code id_token to receive an authorization code and a detached signature. |
client_id Required |
The client_id of your application. |
redirect_uri Required |
The URL to which Auth0 will redirect the browser after authorization has been granted by the user. Specify the redirect_uri under your Application's Settings. |
state Recommended |
An opaque value the application adds to the initial request that the authorization server includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks. |
scope Recommended |
OIDC scopes and custom API scopes. For example: openid read:timesheets . Include offline_access to get a refresh token. |
code_challenge Recommended |
OIDC scopes and custom API scopes. For example: openid read:timesheets . Include offline_access to get a refresh token. |
code_challenge_method Recommended |
Method used to generate the challenge. The PKCE specification defines two methods, S256 and plain, however, Auth0 supports only S256 since the latter is discouraged. [Authorization Code Flow with Proof Key for Code Exchange (PKCE)] (/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce). |
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 application. If null, it will redirect to the Auth0 Login Page and show the Login Widget using the first database connection. |
prompt |
Can be used to force a particular prompt to display, e.g. prompt=consent will always display the consent prompt. |
organization |
ID of the organization to use when authenticating a user. When not provided, if your application is configured to Display Organization Prompt, the user will be able to enter the organization name when authenticating. |
application/x-www-form-urlencoded
strings
for all passed parametersclient_secret
, or client_assertion
and client_assertion_type
for JSON Web Token Client Authentication, or pass a client-certificate
and client-certificate-ca-verified
header when using Mutual TLS).authorization_details
parameter to request permission for each resource. For example, you can specify an array of JSON objects to convey fine-grained information on the authorization. Each JSON object must contain a type
attribute. The rest is up to you to define.GET https://{yourDomain}/authorize
request_uri={yourRequestUri}&
client_id={yourClientId}
After calling the /oauth/par
endpoint, redirect the end user to the /authorize
endpoint using a GET
call.
Parameter | Description |
---|---|
client_id Required |
The client_id of your application. |
request_uri Required |
The request_uri value that was received from the /oauth/par endpoint. |
POST https://{yourDomain}/oauth/par
Content-Type: 'application/x-www-form-urlencoded'
grant_type=code|code id_token&
client_id={yourClientId}&
code=CODE&
redirect_uri={https://yourApp/callback}&
code_verifier=CODE_VERIFIER
curl --request POST \
--url 'https://{yourDomain}/oauth/par' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=authorization_code& client_id={yourClientId}& code=CODE&redirect_uri={https://yourApp/callback}&code_verifier=CODE_VERIFIER'
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: 'CODE',
redirect_uri: '{https://yourApp/callback}',
code_verifier: 'CODE_VERIFIER'
}
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});
RESPONSE SAMPLE:
/**
The `/oauth/token` endpoint will respond with a JSON object containing an `id_token` property, and potentially also a `refresh_token` if one was requested.
*/
HTTP/1.1 200 OK
Content-Type: application/json
{
"refresh_token":"GEbRxBN...edjnXbL",
"access_token":"eybRxBN...edjnXZQ",
"id_token":"eyJ0XAi...4faeEoQ",
"token_type":"Bearer",
"expires_in":86400,
"authrorization_details":[
{
"type":"my_type",
"other_attributes_of_my_type":"value"}
]
},
When users are redirected back to your callback, you need to make a POST
call to the oauth/token
endpoint to exchange an authorization code for an access and/or an ID token.
Parameter | Description |
---|---|
grant_type Required |
Denotes the flow. Assuming you have an authorization code from the /authorize endpoint, use authorization_code . |
code |
The authorization code from the initial /authorize call. |
client_id Required |
The client_id of your application. |
request_uri Required |
This is required only if it was set at the GET /oauth/par endpoint. The values from /authorize must match the value you set at /oauth/token . |
code_verifier Recommended |
Cryptographically random key used to generate the code_challenge passed to /oauth/par . If the code_challenge parameter is passed in the call to /oauth/par , this is required. |
To make a call to /oauth/token
endpoint, you must:
application/x-www-form-urlencoded
strings
for all passed parametersclient_secret
, or client_assertion
and client_assertion_type
for JSON Web Token Client Authentication, or pass a client-certificate
and client-certificate-ca-verified
header when using Mutual TLS).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 application's credentials (a Client ID and a Client Secret).
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. |
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.
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 OpenID Connect (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, id_token to get only an ID token (if you don't plan on accessing an API), or id_token token to get both an ID token and an Access Token. |
client_id Required |
Your application's ID. |
state Recommended |
An opaque value the application adds to the initial request that Auth0 includes when redirecting back to the application. This value must be used by the application 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 for your application. |
prompt |
To initiate a silent authentication request, use prompt=none (To learn more, read the Remarks). |
organization |
ID of the organization to use when authenticating a user. When not provided, if your application is configured to Display Organization Prompt, the user will be able to enter the organization name when authenticating. |
invitation |
Ticket ID of the organization invitation. When inviting a member to an Organization, your application should handle invitation acceptance by forwarding the invitation and organization key-value pairs when the user accepts the invitation. |
redirect_uri
value must be specified as a valid callback URL under your Application's Settings.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.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.
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 Application Settings is Post or Basic . |
audience |
The unique identifier of the target API you want to access. |
username Required |
Resource Owner's identifier, such as a username or email address. |
password Required |
Resource Owner's secret. |
scope |
String value of the different scopes the application 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. |
Parameter | Description |
---|---|
auth0-forwarded-for |
End-user IP as a string value. Set this if you want brute-force protection to work in server-side scenarios. For more information on how and when to use this header, refer to Using resource owner password from server-side. |
scope
parameter will be included in the response JSON.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.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.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. To begin the Device Authorization Flow, your application should first request a device code.
Parameter | Description |
---|---|
audience |
The unique identifier of the target API you want to access. |
scope |
The scopes for which you want to request authorization. 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. |
client_id Required |
Your application's ID. |
Value | Description |
---|---|
device_code |
The unique code for the device. When the user visits the verification_uri in their browser-based device, this code will be bound to their session. |
user_code |
The code that the user should input at the verification_uri to authorize the device. |
verification_uri |
The URL the user should visit to authorize the device. |
verification_uri_complete |
The complete URL the user should visit to authorize the device. Your app can use this value to embed the user_code in the URL, if you so choose. |
expires_in |
The lifetime (in seconds) of the device_code and user_code . |
interval |
The interval (in seconds) at which the app should poll the token URL to request a token. |
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.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.
Parameter | Description |
---|---|
grant_type Required |
Denotes the flow you are using. For Device Authorization, use urn:ietf:params:oauth:grant-type:device_code . |
client_id Required |
Your application's Client ID. |
device_code Required |
The device code previously returned from the /oauth/device/code endpoint. |
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.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.
Parameter | Description |
---|---|
grant_type Required |
Denotes the flow you are using. To refresh a token, use refresh_token . |
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 Application Settings is Post or Basic . |
refresh_token Required |
The refresh token to use. |
scope |
A space-delimited list of requested scope permissions. If not sent, the original scopes will be used; otherwise you can request a reduced set of scopes. Note that this must be URL encoded. |
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.
Parameter | Description |
---|---|
client_id Required |
The client_id of your application. |
client_assertion |
A JWT containing a signed assertion with your application credentials. Required when Private Key JWT is the application authentication method. |
client_assertion_type |
The value is urn:ietf:params:oauth:client-assertion-type:jwt-bearer . Required when Private Key JWT is the application authentication method. |
client_secret |
The client_secret of your application. Required when Client Secret Basic or Client Secret Post is the application authentication method. Specifically required for Regular Web Applications only. |
token Required |
The Refresh Token you want to revoke. |
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.
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 the tenant's configuration settings.
Parameter | Description |
---|---|
auth0-forwarded-for |
End user IP as a string value. Set this if you want brute-force protection to work in server-side scenarios. To learn more about how and when to use this header, read Using resource owner password from server-side. |
grant_type Required |
Denotes the flow you are using. For Token Exchange for Native Social, use urn:ietf:params:oauth:grant-type:token-exchange . |
subject_token Required |
Externally-issued identity artifact representing the user. |
subject_token_type Required |
Identifier that indicates the type of subject_token . |
client_id Required |
Your application's Client ID. |
audience |
The unique identifier of the target API you want to access. |
scope |
String value of the different scopes the application is requesting. Multiple scopes are separated with whitespace. |
user_profile Only For apple-authz-code |
Optional element used for native iOS interactions for which profile updates can occur. Expected parameter value will be JSON in the form of: { name: { firstName: 'John', lastName: 'Smith }} |
scope
parameter will be included in the response JSON.Legacy
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.
Parameter | Description |
---|---|
client_id Required |
The client_id of your application. |
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. |
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.
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.
Parameter | Description |
---|---|
client_id Required |
The client_id of your application |
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 instead of username/password, in Touch ID scenarios. |
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 Touch ID scenarios. Required when grant_type is urn:ietf:params:oauth:grant-type:jwt-bearer |
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.
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.
Parameter | Description |
---|---|
id_token Required |
The ID Token to use. |
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.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.
Parameter | Description |
---|---|
response_type Required |
Use code for server side flows, token for client side flows |
client_id Required |
The client_id of your application |
connection |
The name of the connection configured to your application. 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 |
redirect_uri
value must be specified as a valid callback URL under your Application's Settings.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.
Parameter | Description |
---|---|
access_token Required |
The logged-in user's Access Token |
user_id Required |
The logged-in user's user_id |
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.
Parameter | Description |
---|---|
client_id Required |
Τhe client_id of your app |
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. |
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.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.
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 . |
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.
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.
Parameter | Description |
---|---|
client_id Required |
Your application's Application ID. |
connection Required |
The name of the connection configured to your application |
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 Touch ID scenarios. |
device |
You should set this to a string, if you are requesting a Refresh Token (scope=offline_access ). |
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.
Errors
The Authentication API may return the following HTTP Status Codes:
Status | JSON Response |
---|---|
400 Bad Request | {"error": "invalid_request", "error_description": "..."} |
400 Bad Request | {"error": "invalid_request", "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": "..."} |
Status | JSON Response |
---|---|
200 Success | {"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 Bad Request | {"error": "invalid_request", "error_description": "..."} The required parameters were not sent in the request. |
401 Unauthorized | {"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. |
Status | JSON Response |
---|---|
400 Bad Request | {"error": "invalid_request", "error_description": "the connection was disabled"} The connection is not active or not enabled for your client_id . |
400 Bad Request | {"error": "invalid_request", "error_description": "the connection was not found"} |
400 Bad Request | {"error": "invalid_request", "error_description": "missing client_id parameter"} |
400 Bad Request | {"error": "invalid_request", "error_description": "missing access_token parameter"} |
401 Unauthorized | {"error": "invalid_request", "error_description": "invalid access_token: invalid_token"} The access_token is invalid or does not contain the set scope |
403 Forbidden | {"error": "unauthorized_client", "error_description": "invalid client"} |
Status | JSON Response |
---|---|
400 Bad Request | {"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 Bad Request | {"error": "invalid_request", "error_description": "missing id_token parameter"} For this grant type you need to provide a JWT ID Token |
400 Bad Request | {"error": "invalid_grant", "error_description": "..."} Errors related to an invalid ID Token or user |
Status | JSON Response |
---|---|
400 Bad Request | {"error": "invalid_request", "error_description": "scope parameter must be a string"} Incorrect scope formatting; each scope must be separated by whitespace |
400 Bad Request | {"error": "invalid_request", "error_description": "specified strategy does not support requested operation"} The connection/provider does not implement username/password authentication |
401 Unauthorized | {"error": "invalid_user_password", "error_description": "Wrong email or password."} |
401 Unauthorized | {"error": "unauthorized", "error_description": "user is blocked"} |
401 Unauthorized | { "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 Unauthorized | { "error": "requires_verification", "error_description": "Suspicious request requires verification" } |
429 Too Many Requests | {"error": "too_many_attempts", "error_description": "..."} Some attack protection features will return this error |
429 Too Many Requests | {"error": "too_many_logins", "error_description": "..."} Some attack protection features will return this error |
Status | JSON Response |
---|---|
400 Bad Request | {"error": "invalid_request", "error_description": "missing client_id parameter"}< |
400 Bad Request | {"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 Bad Request | {"error": "invalid_request", "error_description": "The connection is not yet configured..."} The connection is not properly configured with custom scripts |
400 Bad Request | {"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 Bad Request | {"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 Forbidden | {"error": "unauthorized_client", "error_description": "invalid client"} The provided client_id is not valid |
403 Forbidden | {"error": "access_denied", "error_description": "..."} Validation of specific points raised an access issue |
Status | JSON Response |
---|---|
400 Bad Request | {"error": "bad.tenant","error_description": "error in tenant - tenant validation failed: invalid_tenant"} |
400 Bad Request | {"error": "bad.client_id", "error_description": "Missing required property: client_id"} |
400 Bad Request | {"error": "bad.connection", "error_description": "Missing required property: connection"} |
400 Bad Request | {"error": "bad.connection", "error_description": "Connection does not exist"} |
400 Bad Request | {"error": "bad.connection", "error_description": "Connection is disabled"} |
400 Bad Request | {"error": "bad.connection", "error_description": "Invalid connection strategy. It must either be a passwordless connection"} |
400 Bad Request | {"error": "bad.authParams", "error_description": "error in authParams - invalid type: string (expected object)"} |
400 Bad Request | {"error": "bad.request", "error_description": "the following properties are not allowed: <INVALID_PARAMETER_VALUE>"} |
400 Bad Request | {"error": "bad.phone_number", "error_description": "Missing required property: phone_number"} |
400 Bad Request | {"error": "bad.phone_number", "error_description": "String does not match pattern: ^\\+[0-9]{1,15}$"} |
400 Bad Request | {"error": "sms_provider_error", "error_description": "<SPECIFIC_PROVIDER_MESSAGE> (Code: <SPECIFIC_PROVIDER_CODE>)"} |
400 Bad Request | {"error": "invalid_request","error_description": "Expected auth0-forwarded-for header to be a valid IP address."} |
400 Bad Request | {"error": "bad.tenant","error_description": "error in tenant - could not find tenant in params"} |
400 Bad Request | {"error": "server_error","error_description": "error resolving client"} |
400 Bad Request | {"error": "invalid_request","error_description": "The client_id in the authentication header does not match the client_id in the payload"} |
400 Bad Request | {"error": "bad.connection","error_description": "Public signup is disabled"} |
400 Bad Request | {"error": "bad.connection","error_description": "Unknown error"} |
401 Unauthorized | {"error": "server_error","error_description": "user is blocked"} |
403 Forbidden | {"error": "unauthorized_client","error_description": "Client authentication is required"} |
500 Internal Server Error | {"error": "server_error","error_description": "IdP Error"} |
Status | JSON Response |
---|---|
400 Bad Request | {"error": "invalid_request", "error_description": "missing username parameter"} |
400 Bad Request | {"error": "invalid_request", "error_description": "scope parameter must be a string"} Incorrect scope formatting; each scope must be separated by whitespace |
400 Bad Request | {"error": "invalid_request", "error_description": "missing client_id parameter"} |
400 Bad Request | {"error": "invalid_request", "error_description": "the connection was not found"} |
400 Bad Request | {"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 Bad Request | {"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 Bad Request | {"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 |
400 Bad Request | "error": "bad.tenant","error_description": "error in tenant - could not find tenant in params" |
400 Bad Request | {"error": "bad.tenant","error_description": "error in tenant - tenant validation failed: "} |
400 Bad Request | {"error": "bad.connection","error_description": "Connection does not exist"} |
400 Bad Request | {"error": "bad.connection","error_description": "Invalid connection strategy. It must either be a passwordless connection"} |
400 Bad Request | {"error": "bad.connection","error_description": "The connection is disabled"} |
401 Unauthorized | {"error": "invalid_user_password", "error_description": "Wrong email or password."} |
401 Unauthorized | {"error": "unauthorized", "error_description": "user is blocked"} |
403 Forbidden | {"error": "unauthorized_client", "error_description": "invalid client"} The provided client_id is not valid |
403 Forbidden | {"error": "access_denied", "error_description": "..."} Validation of specific points raised an access issue |
429 Too Many Requests | {"error": "too_many_attempts", "error_description": "..."} Some attack protection features will return this error |
500 Bad Request | {"error": "server_error","error_description": "..."} |