Authentication API

Documentation Index

Fetch the complete documentation index at: https://auth0-feat-authentication-api-migration.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

The Authentication API enables you to manage all aspects of user identity when you use Auth0. It offers endpoints so your users can log in, sign up, log out, access APIs, and more. The API supports various identity protocols, like OpenID Connect, OAuth 2.0, FAPI and SAML.

​

Base URL

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

​

Authentication methods

You have five options for authenticating with this API:

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

​

OAuth2 Access Token

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.

​

Client ID and Client Assertion

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.

​

Client ID and Client Secret

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

​

Client ID

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.

​

mTLS Authentication

Generate a certificate, either self-signed or certificate authority signed. Then, set up the customer edge network that performs the mTLS handshake. Once your edge network verifies the certificate, forward the request to the Auth0 edge network with the following headers:

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

To learn more, read Authenticate with mTLS.

​

Parameters

For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter: GET https://{yourDomain}/some-endpoint?param=value&param=value For POST requests, parameters not included in the URL should be encoded as JSON with a Content-Type of application/json: curl --request POST --url 'https://{yourDomain}/some-endpoint' --header 'content-type: application/json' --data '{"param": "value", "param": "value"}'

​

Code samples

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

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

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

​

Testing

You can test the endpoints using the Authentication API Debugger.

​

Authentication API Debugger

The Authentication API Debugger is an Auth0 extension you can use to test several endpoints of the Authentication API. Install Debugger 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. To learn more about tenant regions, read Create Tenants.

​

Configure Connections

1. 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).
2. Copy the Callback URL and set it as part of the Allowed Callback URLs of your Application Settings.
3. At the OAuth2 / OIDC tab, select OAuth2 / OIDC Login.

​

Endpoint options

Configure other endpoints with the following options:

• Passwordless: On the OAuth2 / OIDC tab, set Username to the user’s phone number if connection=sms, or the user’s email if connection=email, and Password to the user’s verification code. Click Resource Owner Endpoint.
• SAML SSO: On the Other Flows tab, select SAML.
• WS-Federation: On the Other Flows tab, select WS-Federation.
• Logout: On the Other Flows tab, select Logout, or Logout (Federated) to log the user out of the identity provider as well.
• Legacy Login: On the OAuth2 / OIDC tab, set the fields ID Token, Refresh Token and Target Client ID. Click Delegation.
• Legacy Delegation: On the OAuth2 / OIDC tab, set Username and Password. Click Resource Owner Endpoint.
• Legacy Resource Owner: On the OAuth2 / OIDC tab, set the Username and Password, then select Resource Owner Endpoint.

​

Authentications flows

Configure authentication flows with the following options:

• Authorization Code Flow: On the OAuth2 / OIDC tab, set the field Authorization Code to the code you retrieved from Authorization Code Grant, and the Code Verifier to the key. Click OAuth2 Code Exchange.
• Authorization Code Flow + PKCE: On the OAuth2 / OIDC tab, set the field Authorization Code to the code you retrieved from Authorization Code Grant, and the Code Verifier to the key. Click OAuth2 Code Exchange.
• Client Credential Flow: On the OAuth2 / OIDC tab, select OAuth2 Client Credentials.

​

Errors

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

​

Rate limiting

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.

​

Support

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.