How to implement the Implicit Grant

This tutorial will help you implement the Implicit Grant. If you are looking for some theory on the flow refer to Call APIs from Client-side Web Apps.

The Implicit Grant is an OAuth 2.0 flow that client-side apps use in order to access an API. In this document we will work through the steps needed in order to implement this: get the user's authorization, get a token and access an API using the token.

Before you begin this tutorial, do the following:

1. Get the User's Authorization

First, your app should get consent from the user to invoke the API on their behalf. Auth0 will authenticate the user and obtain consent, unless consent has been previously given.

To initiate the flow, send the user to the authorization URL:



  • audience: The unique identifier of the API the app wants to access. Use the Identifier value on the Settings tab for the API you created as part of the prerequisites for this tutorial.

  • 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). Note that user's consent will be requested, every time the scope value changes.

  • response_type: Indicates the type of credentials returned in the response. For this flow you can either 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: Your application's Client ID. You can find this value at your Application's Settings.

  • redirect_uri: The URL to which the Auth0 will redirect the user's browser after authorization has been granted by the user. The Access Token (and optionally an ID Token) will be available in the hash fragment of this URL. This URL must be specified as a valid callback URL under your Application's Settings.

    Per the OAuth 2.0 Specification, Auth0 removes everything after the hash and does not honor any fragments.

  • state: 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. For more information, see State Parameter.

  • nonce: A string value which will be included in the response from Auth0, used to prevent token replay attacks. It is required for response_type=id_token token.

For example:

<a href="https://YOUR_DOMAIN/authorize?scope=appointments%20contacts&audience=appointments:api&response_type=id_token%20token&client_id=YOUR_CLIENT_ID&redirect_uri=https://YOUR_APP/callback&nonce=12345789">
  Sign In

2. Extract the Access Token

After Auth0 has redirected back to the app, the hash fragment of the URL contains the following parameters:

  • id_token: contains an ID Token and is present if the request parameter response_type included the value id_token, or the scope request parameter the value openid
  • access_token: contains an Access Token and is present if the request parameter response_type included the value token
  • token_type: denotes the type of the Access Token
  • expires_in: the lifetime in seconds of the Access Token. For example, the value 3600 denotes that the Access Token will expire in one hour from the time the response was generated
  • state: present in the response if the state parameter was present in the request. Holds the exact value received from the client in the request.

You can extract the access_token, and other parameters, from the hash fragment of the URL:

function getParameterByName(name) {
  var match = RegExp('[#&]' + name + '=([^&]*)').exec(window.location.hash);
  return match && decodeURIComponent(match[1].replace(/\+/g, ' '));

function getAccessToken() {
  return getParameterByName('access_token');

function getIdToken() {
  return getParameterByName('id_token');

$(function () {
  var access_token = getAccessToken();

  // Optional: an ID Token will be returned by Auth0
  // if your response_type argument contained id_token
  var id_token = getIdToken();

  // Use the Access Token to make API calls
  // ...

3. Call the API

Once you have the access_token you can use it to make calls to the API, by passing it as a Bearer Token in the Authorization header of the HTTP request:

// Use the Access Token to make API calls
$('#get-appointments').click(function(e) {

    cache: false,
    url: "http://localhost:7001/api/appointments",
    headers: { "Authorization": "Bearer " + access_token }

4. 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, see Validate Access Tokens.

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:

function(user, context, callback) {

  // add custom claims to Access Token and ID Token
  context.accessToken['http://foo/bar'] = 'value';
  context.idToken['http://fiz/baz'] = 'some other value';

  // change scope
  context.accessToken.scope = ['array', 'of', 'strings'];

  callback(null, user, context);

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 Implicit grant, you can look at the context.protocol property in your rule. If the value is oidc-implicit-profile, then the rule is running during the Implicit grant.

Optional: Silent Authentication

If you need to authenticate your users without a login page (for example, when the user is already logged in via Single Sign-on (SSO) scenario) or get a new access_token (thus simulate refreshing an expired token), you can use Silent Authentication.

For details on how to implement this, refer to Silent Authentication.

Sample application

For an example implementation see the SPA + API architecture scenario.

This is a series of tutorials that describe a scenario for a fictitious company. The company wants to implement a single-page web app that the employees can use to send their timesheets to the company's Timesheets API using OAuth 2.0. The tutorials are accompanied by a sample that you can access in GitHub.

Keep reading