How to implement the Resource Owner Password Grant

In this tutorial, we will go through the steps required to implement the Resource Owner Password Grant.

You should use this flow only if the following apply:

  • The application is absolutely trusted with the user's credentials. For Single-Page Apps and Native/Mobile Apps, we recommend using web flows instead.
  • Using a redirect-based flow is not possible. If this is not the case and redirects are possible in your application, you should use the Authorization Code Flow instead.

Create an API

Before you start

  • Check that your application's grant type property is set appropriately
  • Register the API with Auth0
  • Check that the Default Audience and/or Default Directory has been set appropriately
  • Update or disable any rules, such as rules that deny access based on an email domain whitelist, so they only impact specific connections. If you get an 'access_denied' error when testing the Password Grant, this could be due to an access control rule.

Create the Backend API

Configure your tenant

The Password Grant relies on a connection capable of authenticating users via username and password. In order to indicate which connection the Password Grant should use you need to set the value of the default_directory tenant setting.

  1. Open the Dashboard and browse to your Tenant Settings.
  2. Scroll down to the Settings section and locate the Default Directory setting.
  3. Enter the name of the connection you would like to use. Keep in mind that only connections capable of authenticating users via username and password can be used (such as database connections, AD, LDAP, Windows Azure AD, ADFS)

Update Default Directory

Proxy to Backend API

Ask for a Token

In order to execute the flow the application needs to acquire the Resource Owner's credentials, usually this will be through the use of an interactive form. Once the application has the credentials it needs to forward them to Auth0 with a POST to the /oauth/token endpoint of Auth0's Authentication API.


  • grant_type: This must be password.
  • username: The end user's identifier.
  • password: The end user's password.
  • audience: The Identifier value on the Settings tab for the API you created as part of the prerequisites for this tutorial.
  • client_id: Your application's Client ID. You can find this value at the Settings tab of the Machine to Machine Application.
  • client_secret: Your application's Client Secret. You can find this value at the Settings tab of the Machine to Machine Application. This is required when the Token Endpoint Authentication Method field at your Application Settings is Post or Basic. Do not set this parameter if your application is not highly trusted (for example, SPA).
  • scope: String value of the different scopes the application is asking for. Multiple scopes are separated with whitespace.

The response contains a signed JSON Web Token (JWT), the token's type (which is Bearer), and in how much time it expires in Unix time (86400 seconds, which means 24 hours).

In case the scopes issued to the application differ from the scopes requested, a scope parameter will be included in the response JSON, listing the issued scopes.

Password grant and standard scopes

If no API scopes (such as read:notes) are included in the request, all API scopes (such as read:notes, create:notes, and so on.) are included in the Access Token. If only the openid scope is included in the request, all openid standard scopes will be returned, such as openid profile email address phone. In these cases, the scope parameter will be included in the response, listing the issued scopes. This happens because a password is equal to full access and hence any password-based exchange gives access to all scopes.

How to get the user's claims

If you need the user's claims you can include the scope openid to your request. If the API uses RS256 as the signing algorithm, the Access Token will now also include /userinfo as a valid audience. You can use this Access Token to invoke the /userinfo endpoint and retrieve the user's claims.

Update the Authentication Service

Realm Support

A extension grant that offers similar functionality with the Resource Owner Password Grant, including the ability to indicate a specific realm, is the

Realms allow you to keep separate user directories and specify which one to use to the token endpoint.

To use this variation you will have to change the following request parameters:

  • Set the grant_type to
  • Set the new request parameter 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.

Auth0 Connections as Realms

You can configure Auth0 Connections as realms, as long as they support active authentication. This includes Database, Passwordless, Active Directory/LDAP, Windows Azure AD and ADFS connections.

Add Audience

Use the token

Once the Access Token has been obtained it can be used to make calls to the Resource Server by passing it as a Bearer Token in the Authorization header of the HTTP request:

Manage Access Token

Verify the token

Once your API receives a request with a Bearer Access Token, the first thing to do is to validate the token. This consists of a series of steps, and if any of these fails then the request must be rejected.

For details on the validations that should be performed by the API, refer to Validate an Access Token.

Create an HTTP Interceptor

Optional: Customize the Tokens

You can use Rules to change the returned scopes of the Access Token and/or add claims to it (and the ID Token) with a script like this:

Namespacing Custom Claims

Auth0 returns profile information in a structured claim format as defined by the OpenID Connect (OIDC) specification. This means that in order to add custom claims to ID Tokens or Access Tokens, they must conform to a namespaced format to avoid possible collisions with standard OIDC claims. You can add namespaced claims using Rules.

If you wish to execute special logic unique to the Password exchange, you can look at the context.protocol property in your rule. If the value is oauth2-password, then the rule is running during the password exchange.

Call the API

Optional: Configure MFA

In case you need stronger authentication, than username and password, you can configure multi-factor authentication (MFA) using the Resource Owner Password Grant. For details on how to implement this refer to Multi-factor Authentication and Resource Owner Password.

Optional: Configure Anomaly Detection

When using this flow from server-side applications, some anomaly detection features might fail because of the particularities of this scenario. For details on how to implement this, while avoiding some common issues, refer to Using Resource Owner Password from Server side.

Keep reading