andrea-chiarelli

I have over 20 years of experience as a software engineer and technical author. Throughout my career, I've used several programming languages and technologies for the projects I was involved in, ranging from C# to JavaScript, ASP.NET to Node.js, Angular to React, SOAP to REST APIs, etc.

In the last few years, I've been focusing on simplifying the developer experience with Identity and related topics, especially in the .NET ecosystem.

Principal Developer Advocate

Andrea Chiarelli

Learn how to enable self-subscription in your B2B SaaS application and automate the Organization creation process using the Auth0.NET SDK.

Enable Self-Subscribing Model in Your Blazor B2B SaaS Application

Let’s take an overview of the new Session Management API, which allows you to manage your user sessions.

User session management allows developers to implement features ranging from controlling session concurrency to monitoring and terminating sessions. In this article, we will discuss the Session Management API, which allows you to manage user sessions in applications that integrate with Auth0.

## The Need for Managing User Sessions

When a user logs in to your application using Auth0, at least two sessions are initiated:

- The *Local Session* (*Application Session*). This session exists on your application's side. It typically uses cookies or similar mechanisms to store information like the user's login status, preferences, or any other data relevant to your application's functionality. Its primary role is to indicate to your application whether the user is currently logged in and authorized to access specific resources or features.
- The *Authorization Server Session* (*Auth0 Session*). This session is managed by Auth0's servers. It's typically stored in a cookie within the *auth0.com* domain or a custom domain associated with your Auth0 tenant. It's primarily used by Auth0 to facilitate features like Single Sign-On (SSO) and to determine if a user needs to re-authenticate when accessing other applications within the same Auth0 tenant.

> In case the user authenticates using a third-party Identity provider, such as Google, Facebook, GitHub, or others, you have a third session, the *3d party IdP session*, which tracks the interactions between the user and that Identity provider. See [this document](https://auth0.com/docs/manage-users/sessions/session-layers) for more info.

Your application's sessions are entirely in your hands, although Auth0 SDKs can help you with session creation. Auth0's session management is under Auth0's control. However, thanks to the new [Session Management API](https://auth0.com/docs/manage-users/sessions/manage-user-sessions-with-auth0-management-api), you can now manage Auth0 sessions from your application as well. The ability to manage authenticated user sessions in Auth0 can meet a few needs, such as:

- You can allow users to list their active sessions and close them by remotely logging out.
- You can allow an administrator to list all the user sessions and possibly force any of them to log out for security reasons.
- You can limit the number of concurrent user sessions.

Let's explore how you can use this new API.

## Set Up Access to the Session Management API

To use the Session Management API, you need the [Enterprise plan](https://auth0.com/pricing). If you don't have this plan but want to test the API, you can create a new tenant and get a free trial period.

You can use the Session Management API as you do with all the [Management API](https://auth0.com/docs/api/management/v2): basically, you need to enable your client application, [get an access token](https://auth0.com/docs/secure/tokens/access-tokens/management-api-access-tokens), and call the API endpoints.

### Enable your client

As a first step, you need to enable your client application to use the required scopes to use the Session Management API. In particular:

- The scope `read:sessions` enables your client to list sessions and get details about them.
- The scope `delete:sessions` allows your client to close a session, i.e., logging a user out.

To enable a client to these scopes, go to your [Auth0 dashboard](https://manage.auth0.com/) and select the application you want to enable. Make sure this is a [Machine to Machine application](https://auth0.com/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps). Select the APIs tab on the application page and then toggle the *Authorized* switch button corresponding to the Auth0 Management API, as shown in the following picture:

![Auth0 Management API authorization](https://images.ctfassets.net/23aumh6u8s0i/2Lo0IwblYRUHaYSZumG0KV/5ba4a67cf84835252167fac11102c2c4/auth0-management-api-authorization.png)

Then, expand the Auth0 Management API section and filter the permissions list using the `session` keyword. You should get the `read:sessions` and `delete:sessions` items. Check them as shown in the following picture:

![Auth0 Management API session scopes](https://images.ctfassets.net/23aumh6u8s0i/6hTwgUYPtXviFLa5BlZtph/7167f08b695580ac2aac827a9e0a809f/auth0-management-api-session-scopes.png)

Don't forget to click the *Update* button to save your changes.

### Get an access token

Now, your application must request an access token to call the Management API. Depending on your specific scenario, you can get an access token in different ways. For example, in a test scenario you can [get it manually](https://auth0.com/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-testing#get-access-tokens-manually) from the Auth0 dashboard or you can use cURL, while in a production scenario, your application must request an access code programmatically.

For demonstration purposes, let's see how you can request an access token via cURL:

```bash
curl --request POST \
  --url https://YOUR_AUTH0_DOMAIN/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"https://YOUR_AUTH0_DOMAIN/api/v2/","grant_type":"client_credentials"}'
```

Replace the placeholders `YOUR_AUTH0_DOMAIN`, `YOUR_CLIENT_ID`, and `YOUR_CLIENT_SECRET` with the respective values from your client configuration.

This request generates a response as the following:

```bash
{ "access_token":"eyJhbGci...",
  "scope":"read:sessions delete:sessions",
  "expires_in":86400,
  "token_type":"Bearer"
}
```

You will use the value of the `access_token` property to demonstrate that you are authorized to call the Management API.

### Call the API

Now that you have the access token, you can call the API endpoints by passing it in the `Authorization` header, as shown in the following cURL request:

```bash
curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/AUTH0_API_ENDPOINT' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json'
```

Replace the placeholders `YOUR_AUTH0_DOMAIN`, `YOUR_ACCESS_TOKEN`, and `AUTH0_API_ENDPOINT` with the respective values.

## Managing the User Sessions

Once we have enabled the client and obtained the access token, let's see how to actually use the Session Management API.

Let's start by listing the active sessions of a specific user. You can use the `/api/v2/users/{userId}/sessions` endpoint as shown in the following example:

```bash
curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/users/auth0%7C8374f7459j7493u84335/sessions' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

In this example, you send a GET request to the endpoint by specifying your Auth0 domain, the user ID, and the access token. As a response, you will get a JSON object like the following:

```bash
{
  "sessions": [{
    "id": "2Lw8dT76wJpOl924",
    "user_id": "auth0|8374f7459j7493u84335",
    "created_at": "2024-05-10T12:04:22.3452",
    "updated_at": "2024-05-10T12:04:22.3452",
    "authenticated_at": "2024-05-21T11:29:12.4251",
    "authentication": { "methods":[
      {
        "name": "pwd",
        "timestamp": "2024-05-21T11:29:12.4251"
      }
    ]},
    "idle_expires_at": "2024-05-21T12:29:12.4251",
    "expires_at": "2024-05-21T18:29:12.4251",
    "device": {
      "initial_ip": "142.250.184.206",
      "last_ip": "142.250.184.206",
      "user_agent": "Mozilla/5.0...",
      "initial_asn": "8612",
      "last_asn": "8612"
    },
    "clients":[ {"client_id": "Hwo482a51heU632d34"} ]
    }
  ]
}
```

This is an object with the `sessions` array that lists the user's active sessions. Each session is represented by an object with some properties: the session ID (`id`), the user ID (`user_id`), the time stamp of their authentication (`authenticated_at`), the authentication method (`authentication`), the device on which the session is active (`device`), the application client used by the user (`clients`), etc.

In the example above, only one session is returned for that user.

If you have a session ID, you can access the data about that session by using the `/api/v2/sessions/{id}` endpoint. You can get a session ID from the `sid` claim of the ID or [Logout token](https://auth0.com/docs/authenticate/login/logout/back-channel-logout#tokens-in-oidc-back-channel-logout-communications). The following example shows how to get the session details given its ID:

```bash
curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/sessions/2Lw8dT76wJpOl924' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

You will receive a JSON object representing that single session, as shown in the following:

```bash
{
  "id": "2Lw8dT76wJpOl924",
  "user_id": "auth0|8374f7459j7493u84335",
  "created_at": "2024-05-10T12:04:22.3452",
  "updated_at": "2024-05-10T12:04:22.3452",
  "authenticated_at": "2024-05-21T11:29:12.4251",
  "authentication": { "methods":[
    {
      "name": "pwd",
      "timestamp": "2024-05-21T11:29:12.4251"
    }
  ]},
  "idle_expires_at": "2024-05-21T12:29:12.4251",
  "expires_at": "2024-05-21T18:29:12.4251",
  "device": {
    "initial_ip": "142.250.184.206",
    "last_ip": "142.250.184.206",
    "user_agent": "Mozilla/5.0...",
    "initial_asn": "8612",
    "last_asn": "8612"
  },
  "clients":[ {"client_id": "Hwo482a51heU632d34"} ]
}
```

## Forcing Session Termination

In addition to getting information about the user sessions, you can also terminate them if your application has the `delete:sessions` scope enabled. You can call both endpoints `/api/v2/users/{userId}/sessions` and  `/api/v2/sessions/{id}` using the `DELETE` method. For example, the following cURL command terminates a specific user session:

```bash
curl --request DELETE \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/sessions/2Lw8dT76wJpOl924' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

The following command deletes all the sessions of a specific user:

```bash
curl --request DELETE \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/users/auth0%7C8374f7459j7493u84335/sessions' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Session termination does not automatically log a user out of the application. As mentioned earlier, multiple sessions are involved in an application, and logout must be handled properly. Read [this article to get an idea of logout complexity](https://auth0.com/blog/the-not-so-easy-art-of-logging-out/).

In particular, session termination events are connected to the [OpenID Connect Back-Channel Logout](https://auth0.com/docs/authenticate/login/logout/back-channel-logout) mechanism. Therefore, to trigger application logout through the Session Management API, your application must be configured to use the `session-revoked` initiator. Read [this document](https://auth0.com/docs/authenticate/login/logout/back-channel-logout/oidc-back-channel-logout-initiators#configure-oidc-back-channel-logout-initiators) to learn how to configure your application to use the `session-revoked` initiator.

## Sessions and Refresh Tokens

Session termination forces the user logout. However, if an application requests a refresh token at login time, this refresh token is still available to the application even after the user session terminates.

This may be an intended or unintended situation, depending on the application's specific requirements. For example, consider an application that needs to call an API on a scheduled basis. It needs a refresh token to ensure an access token even if the user does not have an active session. On the other hand, your application can use a refresh token only to renew an access token with a limited lifetime, but you do not want the refresh token to survive the user session.

In the first case, terminating a user session will work as shown so far. You don't need to take an extra step to revoke the refresh token.

In the second case, the session termination is not enough. You also need a way to invalidate the current refresh token. For this purpose, you can use a few endpoints to help you manage refresh tokens.

> To enable your client application to manage refresh tokens, you have to add the `read:refresh_tokens` and `delete:refresh_tokens` scopes to the Management API configuration in the Auth0 dashboard.

The following command shows how to list all the refresh tokens associated with a given user:

```bash
curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/users/auth0%7C8374f7459j7493u84335/refresh-tokens' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

You get a JSON object containing the list of the refresh tokens with all the details, as in the following example:

```bash
{
  "refresh_tokens": [{
    "id": "6srfsU4dh510",
    "user_id": "auth0|8374f7459j7493u84335",
    "client_id": "Hwo482a51heU632d34",
    "created_at": "2024-05-10T12:04:22.3452",
    "updated_at": "2024-05-10T12:04:22.3452",
    "idle_expires_at": "2024-05-21T12:29:12.4251",
    "expires_at": "2024-06-21T18:29:12.4251",
    "session_id": "2Lw8dT76wJpOl924",
    "rotating": true,
    "resource_servers": [{ audience: "http://myapi.com", scopes:"read:users"}] 
  }]
}
```

To delete this specific refresh token, you can call the `/api/v2/refresh-tokens/{tokenId}` endpoint as in the following example:

```bash
curl --request DELETE \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/refresh-tokens/6srfsU4dh510' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Notice how you specify the ID of the refresh token to delete.

If you want to delete all the refresh tokens associated to a user, you can use the following command:

```bash
curl --request DELETE \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/users/auth0%7C8374f7459j7493u84335/refresh-tokens' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

> Consider that refresh token revocation through the `DELETE` command on the endpoints shown above runs asynchronously. This means that refresh tokens are not immediately revoked when the command finishes running.

## Summary

This article has given you an overview of Auth0's Session Management API with some examples of endpoint invocation via cURL. We started with activating the client application and getting the access token, then moved on to getting a user's session list and terminating a specific session.

You then learned about the relationship between sessions and refresh tokens and how to revoke refresh tokens associated with a user.

Now that you have a basic understanding of how to use the Session Management API, you can build a better security experience for your users.


Introducing the Auth0 Session Management API

carla_urrea

I've been working as a software engineer since 2014, particularly as a backend engineer and doing system design. I consider myself a language-agnostic developer but if I had to choose, I like to work with Ruby, Python, and Elixir.  

After realizing how fun it was to create content and share experiences with the developer community I made the switch to Developer Advocacy. I like to learn and work with new technologies. 

When I'm not coding or creating content you could probably find me going on a bike ride, hiking, or just hanging out with my dog, Dasha. 

Senior Developer Advocate

Carla Urrea Stabile

Passkeys allow you to authenticate securely, and they're easy to integrate using Auth0. But what happens after that? Let's learn how to list and revoke passkeys using Auth0.

Passkeys are the replacement for passwords, and they're here to stay. If you have been learning about this new technology, you know that it's still relatively new, but adoption is growing daily. 

Passkeys are available in Auth0, Google, Apple, Github, and many other places. So, there's a chance you are already using passkeys or are starting to implement them. 

In this blog post, you'll learn to manage your passkeys in Auth0 using the Management API. 

## What is a Passkey?

A passkey is a phishing-resistant cryptographic key pair that users can use for passwordless authentication. More specifically, [passkeys are FIDO credentials](https://fidoalliance.org/faqs/#PasskeysFAQs) that are discoverable by browsers or housed within native applications or security keys for passwordless authentication.

If you haven't already, you can [get started with passkeys using Auth0](https://auth0.com/blog/activate-passkeys-let-users-log-in-without-password/). After getting your free account, all you need to do is navigate to the [**Dashboard > Authentication**](https://manage.auth0.com/#/connections/database/), select your **Database Connection**, and activate passkeys under the **Authentication Methods** tab.

![passkeys prompt](https://images.ctfassets.net/23aumh6u8s0i/2dkPgFFDBt3H2ebmyuy9hF/1c060396c5078842ee312817e0bedccb/Uploaded_from_Using_Passkeys_for_a_Seamless_Login_Experience_in_the_Apple_Vision_Pro)


## The Passkey Lifecycle

Let's dive deep into the passkey's lifecycle. 

### Creation 

It all starts by creating a new passkey, and this can happen at different moments throughout the lifecycle of your user account:

- **Create a passkey during the registration flow:** When a user signs up for the first time to a website, they can create a passkey for their account. 
- **Add new passkey to existing account:** Multiple reasons could trigger this scenario; for example, you are starting to roll out passkeys to your users, and when they log in, you prompt them to create a new passkey. Another example is when a user gets a new security key or loses the old one and wishes to create a new passkey in their new device. 

When you create a new passkey, your browser will call the `navigator.credentials.create()` method from the Web Authentication (WebAuthn) API. Your authenticator will cryptographically sign a challenge generated by the relying party. You can [learn more about the registration process here](https://webauthn.me/introduction). 

Note that in the creation process, both the authenticator and the relying party, in this case, your server, will persist their records related to the newly created passkey.

### Read

When you use your passkey to authenticate yourself, you are "reading" your passkey. Technically speaking, when you use your passkey, the browser calls the `navigator.credentials.get()` method from the Web Authentication API, which is a read endpoint. 

In Auth0, you can do this using the Management API, and that's exactly what you'll learn in the next section. 

### Update

Updating a passkey might be a misleading term; **you can't update a passkey itself**, but rather, your users can update some attributes that can help them identify their passkeys, such as the display name.

Note that as a developer, you can't update the attributes of a passkey in the relying party, but your end-users can change the display name of their passkeys in their authenticators. 

In Auth0, your user's passkeys names might look like something like `passkey|<some_string>`, but this is actually the ID that is also being used as the name. 

![passkeys list in Auth0 dashboard](https://images.ctfassets.net/23aumh6u8s0i/7uxxwd3qtKHfk0sP3t1NUJ/70faad079091a9272e3eb33861ff8655/Screenshot_2024-05-08_at_16.15.31.png)

### Delete

Revoking or deleting a passkey is an action you must execute with extreme care. It's essential that before revoking a passkey, your users have another factor in place to authenticate themselves. Auth0 will still support the password reset flow for this user, which would allow a user to recover access to their account if all their passkeys have been revoked. 

Note that because both the relying party and the authenticator have their own record of your passkey when you delete a passkey from the relying party, your users may also have to delete it from their authenticator. 

<include src= "LearnPasskeysCTA"/>

## List Passkeys with Auth0

You can see the list of passkeys for a given user using the Auth0 Dashboard, but if you want to retrieve the list to use it in your application, you can use the Auth0 Management API. 

> Bear in mind you need to enable the use of the Auth0 Management API for your Auth0 Application. You can do so from the **Auth0 Dashboard > APIs > Auth0 Management API**. Find the **Machine to Machine Applications** and your Auth0 Application name and toggle the switch to **Authorized**. You might also need to [enable Client-Credentials Exchange](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow).

A passkey in Auth0 is an authentication method, which means you can use the [`GET  /api/v2/users/{id}/authentication-methods` endpoint](https://auth0.com/docs/api/management/v2/users/get-authentication-methods) to retrieve passkeys for a given user account. The response of this endpoint looks like this: 

```json
[
  {
    "id": "passkey|dev_pzg5wcycfdfd1VZ",
    "type": "passkey",
    "confirmed": true,
    "key_id": "foNlEKGDGREYERxDu3OuXu8sD-rhn1Dsy47HHcwxwg",
    "credential_device_type": "single_device",
    "credential_backed_up": false,
    "identity_user_id": "6657689457685295031f19fb",
    "user_agent": "Chrome 123.0.0 / Mac OS X 10.15.7",
    "public_key": "pQECAyYREGREGRwdnUjPZw9cnElZbv0Q8Axe/NgPBSPmoxJ+86IlggFeeypCWw7eRrgrgrgrrfd5DKYFnarkeoCr6L+1ds4=",
    "created_at": "2024-04-08T15:59:50.762Z",
    "last_auth_at": "2024-04-09T11:35:20.911Z"
  },
  {
    "id": "webauthn-roaming|dev_L7lkgrrgrp4d2x",
    "type": "webauthn-roaming",
    "confirmed": true,
    "name": "carla's key",
    "created_at": "2024-04-26T09:47:15.750Z",
    "last_auth_at": "2024-04-26T09:51:24.089Z",
    "key_id": "O2qqpM1EgSgEaC_NFSOvr0igwNtW91hyGjHNjVCsnjCoLiZzvEvGYOIj_h1SrETGGTRTGRWRk0mmIflkYA",
    "public_key": "pQECAyYgASFYIC9btx34m5xI0Xyr7zpViOVfJQaD2gfDFDDGDFGDFyk2QN6AwjHv1h3Odh+704d8nEbUM1pz+Wf5tyNKTcqg=",
    "relying_party_identifier": "your-tenant.eu.auth0.com"
  }
]
```

In this case, this user has one passkey and one security key enrolled as their authentication methods. To filter them, you can use the field `type` and check for the `passkey` value. 

Here's a code snippet in Ruby that showcases how to call the Auth0 Management API using the [`ruby-auth0` gem](https://github.com/auth0/ruby-auth0). You can find a [list of all the Management API SDK Libraries here.](https://auth0.com/docs/libraries#mgmt)

```ruby
# Initialize the Auth0Client
client = Auth0Client.new(client_id: ENV['AUTH0_CLIENT_ID'],
                         client_secret: ENV['AUTH0_CLIENT_SECRET'],
                         domain: ENV['AUTH0_DOMAIN'])

# Call the Get an authentication method by user id endpoint
passkeys = client.user_authentication_methods(auth0_user_id)

# Select only elements that have the type "passkey"
passkeys = passkeys.select { |p| p["type"] == "passkey" }
```

Where `auth_user_id` is the id of the user in Auth0 (i.e., `auth0|6657689457685295031f19fb` and the values for `client_id`, `client_secret`, and `domain` are set as environment variables. 

The value of the `passkeys` variable would then be: 

```ruby
3.2.2 :010 > passkeys
 => 
[{"id"=>"passkey|dev_pzg5wcycfdfd1VZ",
  "type" => "passkey",
  "confirmed" =>true,
  "key_id"=>"foNlEKGDGREYERxDu3OuXu8sD-rhn1Dsy47HHcwxwg",
  "credential_device_type"=>"single_device",
  "credential_backed_up"=>false,
  "identity_user_id"=>"6657689457685295031f19fb",
  "user_agent"=>"Chrome 123.0.0 / Mac OS X 10.15.7",
  "public_key"=>
   "pQECAyYREGREGRwdnUjPZw9cnElZbv0Q8Axe/NgPBSPmoxJ+86IlggFeeypCWw7eRrgrgrgrrfd5DKYFnarkeoCr6L+1ds4=",
  "created_at"=>"2024-04-08T15:59:50.762Z",
  "last_auth_at"=>"2024-04-09T11:35:20.911Z"}] 
3.2.2 :011 > 
```

## Revoke a Passkey in Auth0

Similarly to listing your passkeys, you can use the [`DELETE  /api/v2/users/{id}/authentication-methods/{authentication_method_id}` endpoint](https://auth0.com/docs/api/management/v2/users/delete-authentication-methods-by-authentication-method-id) to revoke a passkey from a user's authentication methods. 

> Note that before revoking a passkey, you should ensure the user has a fallback authentication factor to allow them to log in. In Auth0, the fallback will automatically be the password reset flow, but you can [enable other factors](https://auth0.com/docs/secure/multi-factor-authentication/multi-factor-authentication-factors#factors).

Here's an example of how to delete an authentication method using the `ruby-auth0` gem to interact with the Auth0 Management API:

```ruby
# Instantiate the Auth0Client if it hasn't been instantiated previously
client = Auth0Client.new(client_id: ENV['AUTH0_CLIENT_ID'],
                         client_secret: ENV['AUTH0_CLIENT_SECRET'],
                         domain: ENV['AUTH0_DOMAIN'])

# Call the delete authentication method endpoint 
client.delete_user_authentication_method(auth0_user_id, auth0_passkey_id)
```

Similarly, here you're reading the values for `client_id`, `client_secret`, and `domain` from the environment; the `auth0_user_id` variable is the user's id in Auth0 and the `auth0_passkey_id` is the passkey's id from Auth0 (i.e., `passkey|dev_pzg5wcyjfdhgkfSC01VZ`)

## Summary 

In this blog post, you learned the basics of the passkey's lifecycle and how to list and revoke passkeys using the Auth0 Management API. You also learned that as an end-user, you could create, read, update, and delete passkeys in your authenticators, and as a developer, you can manage the passkey's lifecycle on the relying party's side.

I’ve Got Passkeys Working in My App! But How Do I Manage Them?

5e074956ee8ba1fea26e30d28c190495?s=300 avatar

5e074956ee8ba1fea26e30d28c190495?s=300

Full stack developer creating content at Auth0. I love taking a deep dive into hard-to-understand concepts and creating content that makes them easier to grasp. In my free time you can usually find me reading, hanging out with my dogs, or curling in the squat rack.

Former Developer Content Manager

Holly Guevara

Learn how to use the Auth0 Management API to build an admin dashboard with Express and Vue



<details>
<summary>Starting from this chapter?</summary>

Clone the application starter repo:

``` bash  
git clone git@github.com:auth0-blog/vue-express-auth.git
```

Follow the directions in the [project README](https://github.com/auth0-blog/vue-express-auth#set-up-the-express-server).

In the [Auth0 dashboard](https://manage.auth0.com/dashboard), click on "APIs" in the left menu and then select "Auth0 Management API". From there, select "Machine to Machine Applications" and find the "Vue Express API" you just created. Click the switch next to it so that it says "Authorized".

![Auth0 authorized API](https://images.ctfassets.net/23aumh6u8s0i/3bnn4TcXg4JJ6Ti42f4ymi/1545602b9f43d8c6dcfafda536730d27/auth0-management-api-authorized)

Next, add permissions to the application. Click on the down arrow V next to the authorized switch. Select `read:users`, `delete:users`, and `read:user_idp_tokens` and then click "Update".

</details>


## Calling the Management API with Express

The Express API is now registered in the dashboard, and the Auth0 Management API is set up and ready to issue an access token to the Express API. So what's next? Now, you have to do the [**client credentials**](https://auth0.com/docs/flows/concepts/client-credentials) dance to get an access token.

## Client Credentials Flow

The [OAuth 2.0 RFC 6794](https://tools.ietf.org/html/rfc6749#section-4.4) defines how trusted clients (your Express API) can use the client credentials to request an access token from a resource owner (the Auth0 Management API):

> ❗ The client can request an access token using only its client credentials (or other supported means of authentication) when the client is requesting access to the protected resources under its control, or those of another resource owner that have been previously arranged with the authorization server (the method of which is beyond the scope of this specification).

Because the Management API access token is requested on behalf of the Express application, not a user, it doesn't make sense to ask for a username and password to verify who the requester is. Instead, you can use the Express application's client credentials (`client_id` and `client_secret`) to authenticate the application.

![Machine to machine client credentials grant](https://images.ctfassets.net/23aumh6u8s0i/3nVhN6jBKCjJxpO2BhcxOW/af8eaeabf5529b52e5e5ce865d045045/auth-sequence-client-credentials)
> This diagram depicts the client credentials grant flow described below

* The Express application authenticates with the Auth0 Authorization Server using its `client_id` and `client_secret`
* The Auth0 Authorization Server validates the  `client_id` and `client_secret`
* The Auth0 Authorization Server issues an access token and passes it back to your application
* The Express application passes this token when it makes a request to the Management API
* The Management API responds with the requested data

## Requesting an Access Token  

The Express application needs to request an access token for the Management API from the Auth0 server. There are **three ways** to do this.

1) Make a `POST` request to the token endpoint using your Express API client ID and client secret, as shown below:

<include src="AmpWarning" fullUrl="https://auth0.com/blog/build-an-admin-dashboard-with-express-and-vue-creating-the-backend"/>

``` js  
let request = require("request");

let options = {
    method: 'POST',
    url: 'https://YOUR-DOMAIN.auth0.com/oauth/token',
    headers: { 'content-type': 'application/json' },
    body: '{
        "client_id": "yourclientid",
        "client_secret": "yourclientsecret",
        "audience": "https://YOUR-DOMAIN.auth0.com/api/v2",
        "grant_type": "client_credentials"
    }'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
});
```

This will return the **access token** (with a 24-hour expiration) and **token type**:

``` js  
{
  "access_token": "somelongstring",
  "token_type": "Bearer"
}
```

2) Use the [Auth0 Node Authentication API Client](https://www.npmjs.com/package/auth0#authentication-api-client)

``` js  
let AuthenticationClient = require('auth0').AuthenticationClient;
 
let auth0 = new AuthenticationClient({
  domain: '{YOUR_ACCOUNT}.auth0.com',
  clientId: '{CLIENT_ID}',
  clientSecret: '{CLIENT_SECRET}'
});
 
auth0.clientCredentialsGrant(
  {
    audience: 'https://{YOUR_ACCOUNT}.auth0.com/api/v2/',
    scope: '{MANAGEMENT_API_SCOPES}'
  },
  function(err, response) {
    if (err) {
      // Handle error.
    }
    console.log(response.access_token);
  }
);
```

This performs a Client Credentials Grant using the `clientId` and `clientSecret` of the client that was registered in the Auth0 dashboard, in this case, the Express API. This will return the **access token**, **scopes**, **expiration**, and **token type**. You'll then send this access token along with every request you make to the Management API.

3) Use the [Auth0 Node Management API Client](https://www.npmjs.com/package/auth0#management-api-client)

``` js  
let ManagementClient = require('auth0').ManagementClient;

let auth0 = new ManagementClient({
  domain: '{YOUR_ACCOUNT}.auth0.com',
  clientId: '{YOUR_CLIENT_ID}',
  clientSecret: '{YOUR_CLIENT_SECRET}',
  scope: 'read:users delete:users'
});
```

Finally, there also exists an option to **automatically receive an access token in the background** using the [Auth0 Node Management API Client](https://www.npmjs.com/package/auth0#management-api-client). This is similar to option 2. The Client Credentials Grant still takes place behind the scenes and will retrieve a Management API access token along with its expiration. It then automatically caches this access token for the time specified in the expiration.

For this tutorial, you'll be using the third option. This option allows you to use the [Management Client to easily make requests to the Management API](https://auth0.github.io/node-auth0/module-management.ManagementClient.html).

## Getting your Access Token in Express

Now that you know how the client credentials flow works and how you're going to implement it in your application, it's finally time to write some code!

Head back to your code editor and open `server/server.js` from the [Vue Express application you cloned earlier](https://github.com/auth0-blog/vue-express-auth).

📝 Here's an overview of what you're going to do:

- Install and import the Auth0 `ManagementClient`
- Create a `.env` file for your confidential values
- Add `clientId` and `clientSecret` to your `authConfig` object
- Create a new instance of the `ManagementClient` with your `domain`, `clientId`, and `clientSecret`

Make sure you're in the `server` directory in your terminal and install the [`node-auth0`](https://www.npmjs.com/package/auth0) package by running:

``` bash  
npm install auth0
```

Find the `require` functions at the top of your `server/server.js` file and add the following line to import `ManagementClient`.

``` js  
// ...
// import statements
const ManagementClient = require('auth0').ManagementClient;
// app.use 
```

Next, toward the top of the file, you should see an `authConfig` object directly underneath the `require` and `use` methods. This needs to be modified to include your client secret and client ID from the Express API.

Because these are sensitive values, you should not save them directly in the code. If you ever share this code or upload it to GitHub, you [risk leaking your client secret](https://auth0.com/blog/developers-guide-to-common-vulnerabilities-and-how-to-prevent-them/#Mishandling-Sensitive-Data). Instead, it's best to create a `.env` file and add this file to your `.gitignore`. To do this, navigate to the `server` directory and run the following command in your terminal: 

``` bash  
npm install dotenv
```

At the top of your `server/server.js` file add this line:

``` js  
require('dotenv').config();
```

Now create a file in the root of the `server` directory called `.env` and add the following to it:

``` js  
AUTH0_DOMAIN = your-domain.auth0.com
AUTH0_AUDIENCE = https://your-api-audience.com
CLIENT_ID = yourclientid
CLIENT_SECRET = yourclientsecret
```

The values for `CLIENT_ID` and `CLIENT_SECRET` can be found back in the [Auth0 dashboard](https://manage.auth0.com/dashboard) on the Auth0 Management API page that you set up earlier.

If you already closed this tab, just click on "**APIs**" > "**Auth0 Management API**" > "**Test**" and then select the Express API from the dropdown. Next, click on "**Node.JS**", and you can copy the `client_id` and `client_secret` from the resulting code below.

If you followed the setup instructions from the README, you should already have an object in `server.js` called `authConfig` that contains the audience and domain values. Grab those and paste them into their corresponding spots in `.env`.

If you don't have the domain and audience values, they can be found by clicking on "**APIs**" in the left-hand menu and then selecting the Vue Express API. Next, click on "**Quick Start**" and then select "**Node.js**". You'll see a value for `audience`, which you can paste directly into `AUTH0_AUDIENCE` and then another value for `issuer`. Copy this and paste it into `AUTH0_DOMAIN`.

> ⚠️ Important: For `AUTH0_DOMAIN`, omit the `https://` and the trailing `/`. It should be formatted exactly as shown above.

Next, modify the `authConfig` object in `server/server.js` to use those environment variables as follows:

``` js  
// Set up Auth0 configuration
const authConfig = {
  domain: process.env.AUTH0_DOMAIN,
  audience: process.env.AUTH0_AUDIENCE,
  clientId: process.env.CLIENT_ID,
  clientSecret: process.env.CLIENT_SECRET
};
```

And finally, you'll create a new instance of the `ManagementClient`, which takes an object that contains your Auth0 domain, client ID, and client secret.

Paste this just below the `authConfig` object in `server/server.js`:

``` js  
const managementAPI = new ManagementClient({
  domain: authConfig.domain,
  clientId: authConfig.clientId,
  clientSecret: authConfig.clientSecret
});
```

Now, when you use `managementAPI`, it will automatically perform the Client Credentials Grant in the background using the domain, client ID, and the client secret, which will result in an access token that can be used to make requests to the Management API.

Now it's time to test it out.

## Calling the Management API

Back in `server/server.js`, scroll down to where the `events` array is defined. Paste in the following code right below it:

``` js  
app.get('/users', (req, res) => {
  managementAPI
    .getUsers()
    .then(function(users) {
      res.send(users);
    })
    .catch(function(err) {
      console.log(err);
    });
});
```

This will create an API route in your Express application that calls the [Management API Node Client to get all users](https://auth0.github.io/node-auth0/module-management.ManagementClient.html#getUsers) whenever that route is accessed.

To verify that it's working, switch to your terminal and start your Express application if you haven't already by running:

``` bash  
npm start
```

Navigate to [`http://localhost:8000/users`](http://localhost:8000/users) in your browser, and you should see all of the users that have signed up for your application! 💃

If you're getting an error, **reach out in the comments below**, and I'll try to help troubleshoot.

You're also going to need a route to delete a user, so since you're here, just set that up now. Below the previous route, paste in:

``` js  
app.get('/users/:id/delete', (req, res) => {
  managementAPI
  .deleteUser({ id: req.params.id })
  .then(response => {
    res.send('User deleted!');
  })
  .catch(function(err) {
    res.send(err);
  });
});
```

This will grab the `id` of the user, which will be passed to the server from the Vue client. Then it will call the Management API to do the deletion.

Now that you're able to pull all of your users into the application and delete a user, it's time to switch to the frontend.

<include src="tutorial/NextButton" nextPart="build-an-admin-dashboard-with-express-and-vue-creating-the-frontend/" completedMessage="I've set up the Express backend"/>

<include src="tutorial/IssueButton" communityTopic="53302"/>


Build an Admin Dashboard with Express and Vue: Creating the Backend



<details>
<summary>Starting from this chapter?</summary>

**Setting up**

Clone the application starter repo and check out the `creating-the-frontend` branch:

``` bash  
git clone git@github.com:auth0-blog/express-vue-management-api.git --branch creating-the-frontend
```

Install the dependencies for both the client and server:

``` bash  
cd server
npm install
cd ../client
npm install
```

**Configure Auth0**

Follow the Auth0 Configuration directions in the [project README of the starter Vue and Express application](https://github.com/auth0-blog/vue-express-auth#configuring-auth0).

**Configure Management API**

In the [Auth0 dashboard](https://manage.auth0.com/dashboard), click on "APIs" in the left menu and then select "Auth0 Management API". From there, select "Machine to Machine Applications" and find the "Vue Express API" you just created. Click the switch next to it so that it says "Authorized".

![Auth0 authorized API](https://images.ctfassets.net/23aumh6u8s0i/3bnn4TcXg4JJ6Ti42f4ymi/1545602b9f43d8c6dcfafda536730d27/auth0-management-api-authorized)

Next, add permissions to the application. Click on the down arrow V next to the authorized switch. Select `read:users`, `delete:users`, and `read:user_idp_tokens` and then click "Update".

Create the `.env` file in the root of the `server` directory:

``` js  
AUTH0_DOMAIN = your-domain.auth0.com
AUTH0_AUDIENCE = https://your-api-audience.com
CLIENT_ID = yourclientid
CLIENT_SECRET = yourclientsecret
```

To find your values, go to the [Auth0 dashboard](https://manage.auth0.com/dashboard) and click:

"APIs" > "Auth0 Management API" > "Test"

Select the Express API from the dropdown then click "Node.JS". You'll find the values for `CLIENT_ID` AND `CLIENT_SECRET` in the resulting code.

`AUTH0_DOMAIN` and `AUTHO_AUDIENCE` can be found by clicking on "APIs" and then selecting the Vue Express API. Then click on "Quick Start" and select "Node.js". You'll see a value for audience, which you can paste directly into AUTH0_AUDIENCE and then another value for issuer. Copy this and paste it into AUTH0_DOMAIN, but leave off the `https://` and the trailing `/` at the end.

**Test it**

Start the Vue app:

``` bash  
cd client
npm run serve
```

Start the Express app:

``` bash  
cd server
npm start
```

Navigate to [http://localhost:8000/users](http://localhost:8000/users) to see an array all of your users from the Express `/users` endpoint.

View the dashboard at: [http://localhost:8080/dashboard](http://localhost:8080/dashboard)

> Note: Don't click the Delete Me button yet!
</details>

## Require Admin Role to Access User Information

It's fantastic not to be required to go to your Auth0 management dashboard to manage the users that have signed up for your application. However, there's still a big problem here. Currently, **everyone** can see that list of users. You actually don't even need to be logged in to see them. Go ahead and open [`http://localhost:8080/dashboard`](http://localhost:8080/dashboard) in an incognito window to see for yourself. 

The Express `getUsers()` and `deleteUser()` functions only run if there is a valid Management API access token issued from the Authorization server. The **Express Application itself has been authorized in the Auth0 dashboard and can always prove itself to the Management API using the client credentials in the `.env` file**. So as long as that exists and the access isn't revoked from the Auth0 dashboard side, the Express application can always get a valid access token and retrieve the requested Management API data.

This is really no different than if you had **an API that reached out to your own database** for some confidential data. If you wanted to grab a list of users from your MySQL database for your administrators to see in their dashboard, you'd maybe create an `admin` role with a `manage:users` permission. Then you'd require that in order to access those endpoints that pull user data, the user must have that `admin` role with the correct permission. That's exactly what you're going to do here to protect the two Express endpoints that you created.

That's the long explanation for *why* you need to secure your Express API, but *how* do you do this?

Here are the general steps you need to follow, and then in the next section, you'll see how to execute them.

**Steps for Adding Authorization to your API**

- Create an Express API `manage:users` permission in the Auth0 dashboard
- Install the Express authorization package, `express-jwt-authz`
- Require the authorization package in your Express application
- Protect the `/users` and `/users/:id/delete` routes by requiring an access token
- Pass the access token when making the request on the Vue side
- Check the access token for the `manage:users` scope
- Enable RBAC settings in the Auth0 dashboard

<include src="SmallBannerCTA" text="Want to take your Authorization to the next level? → " linkText="fga.dev" link="https://a0.to/oktafga_blog" imgLink="https://cdn.auth0.com/website/blog/banners/fga.png" imgAlt="Okta FGA Logo" />

## Create the Express API Permission

First, head back to the [Auth0 dashboard](https://manage.auth0.com/dashboard) and find your Vue Express API under "**APIs**".

Click on "**Permissions**" and create a new permission called `manage:users`. For the description, you can just write "Manage users" or be as descriptive as you'd like. Make sure you click "**Add**" to save it.

![Auth0 Express API permissions](https://images.ctfassets.net/23aumh6u8s0i/dQHdrN2y9UUn3U6CROBwF/7a05bf0e473144e81073e39c334f380a/express-api-user-permissions)

## Integrate into the Express Application

Next, in the `server` directory, install the [express-jwt-authz](https://github.com/auth0/express-jwt-authz) package. This is required to check if the access token contains the required scopes/permissions, which in this case, will be `manage:users`.

``` bash  
npm install express-jwt-authz
```

Require this new package at the top of the Express application in `server/server.js` where the rest of the `require` methods are.

``` js  
// server/server.js
// other require methods
const jwtAuthz = require('express-jwt-authz'); // 👈 new code

// This should already exist in your application if you cloned it from GitHub
// Authentication middleware to verify access token against Auth0 JSON Web Key Set
const checkJwt = jwt({
  // Provide a signing key based on the key identifier in the header and the signing keys provided by your Auth0 JWKS endpoint.
  secret: jwksRsa.expressJwtSecret({
    cache: true,
    rateLimit: true,
    jwksRequestsPerMinute: 5,
    jwksUri: `https://${authConfig.domain}/.well-known/jwks.json`
  }),

  // Validate the audience (Identifier) and the issuer (Domain).
  audience: authConfig.audience,
  issuer: `https://${authConfig.domain}/`,
  algorithms: ["RS256"]
});
```

Next, take a look at the `checkJwt` middleware. This should already exist from when you cloned the starter application. This middleware is responsible for checking if the JWT that the client provides is valid.

> On a side note, if you're interested in learning about JSON Web Tokens, click the link below and we'll email you our in-depth **JWT Handbook** for free!

<include src="ebook-ads/JwtHandbook" />

## Protect the Express Endpoint

Now it's time to secure the `/users` endpoint. In `server.js`, find the two routes you created and add the `checkJWT` middleware to them:

``` js  
app.get('/users', checkJwt, (req, res) => {
  managementAPI
    .getUsers()
    .then(function(users) {
      res.send(users);
    })
    .catch(function(err) {
      res.send(err);
    });
});

app.get('/users/:id/delete', checkJwt, (req, res) => {
  managementAPI
    .deleteUser({ id: req.params.id })
    .then(response => {
      res.send('User deleted!');
    })
    .catch(function(err) {
      res.send(err);
    });
});
```

Now a user has to be signed in to make requests to these two endpoints. However, **this isn't enough**. You still need to check if the user has the **required permissions** to access the endpoints. 

## Check for Appropriate Permissions

This is where the `express-jwt-authz` package comes into play. You can use this package to check that the `manage:users` permission exists in the access token. You'll create a new middleware, `checkPermissions`, that will run before those two routes.

By default, the `express-jwt-authz` package checks the `scope` claim for the permission. You can, however, [pass in an option called `customScopeKey`](https://github.com/auth0/express-jwt-authz#options), which tells it to look in `user.permissions` to match the required permission. 

Define the new middleware, `checkPermissions`, right underneath `checkJwt`. For the first parameter, you'll pass in an array of the permission(s) you want to check for, which in this case is `manage:users`. The second parameter will be the `customScopeKey` option mentioned above. Then you'll add this middleware to the two routes you want to protect:

``` js  
// ..
// const checkJwt = jwt({...});

const checkPermissions = jwtAuthz([ 'manage:users' ], { customScopeKey: 'permissions' });

// let events = [...];

app.get('/users', checkJwt, checkPermissions, (req, res) => {
  managementAPI
    .getUsers()
    .then(function(users) {
      res.send(users);
    })
    .catch(function(err) {
      res.send(err);
    });
});

app.get('/users/:id/delete', checkJwt, checkPermissions, (req, res) => {
  managementAPI
  .deleteUser({ id: req.params.id })
  .then(response => {
    res.send('User deleted!');
  })
  .catch(function(err) {
    res.send(err);
  });
});
```

Now, the Vue client will be required to present a valid access token with the `manage:users` permission on behalf of the user before these routes will run. This wasn't required before, so the Vue `UserService` isn't currently **passing a token in the header** when it makes a request to the Express endpoints. Go ahead and fix that now.

## Add Access Token to the Request

Back on the client side, open up `client/src/views/Dashboard.vue` and scroll down to the `getUserData()` method. In the [Vue Login](https://auth0.com/blog/beginner-vuejs-tutorial-with-user-login/) article, you added a Vue authentication wrapper (provided by Auth0), which integrates Auth0 login into your Vue application. This plugin wrapper can be accessed from inside Vue components to check if a user is signed in. 

Since the user's access token is required to make a request to the Express API, you need to grab the token, if it exists, and pass it to the UserService where the Express API call is made.

Modify your `getUserData()` and `deleteUser()` methods like so:

``` js  
async getUserData() {
  // Get the access token from the auth wrapper
  const accessToken = await this.$auth.getTokenSilently(); // 👈 NEW

  // Pass the access token to the getUsers service
  UserService.getUsers(accessToken) // 👈 NEW
    .then(
      (users => {
        this.$set(this, "users", users);
      }).bind(this)
    );
},
async deleteUser(deleteId) {
  // Get the access token from the auth wrapper
  const accessToken = await this.$auth.getTokenSilently(); // 👈 NEW
  // Pass the access token to the getUsers service
  UserService.deleteUser(accessToken, deleteId) // 👈 NEW
  .then(
    (response => {
      this.message = response;
      this.getUserData(); // get refreshed users
    })
  );
}
```

Next, you need to pass this token along with the request in the UserService. Open up `client/src/services/UserService.js` and modify the `getUsers` method to add a header object to the request. This Authorization header will send the access token to the Express API. If the token is valid, the Express API will send back the data. Repeat this on the `deleteUser()` method.

``` js  
async getUsers(accessToken) {
  let res = await axios.get("http://localhost:8000/users", {
    headers: {
      Authorization: `Bearer ${accessToken}`
    }
  });
  console.log(res.data);
  return res.data;
},
async deleteUser(accessToken, id) {
  let res = await axios.get(`http://localhost:8000/users/${id}/delete`, {
    headers: {
      Authorization: `Bearer ${accessToken}`
    }
  });
  return res.data;
}
```

Now, if you go back to the Vue dashboard, [`http://localhost:8080/dashboard`](http://localhost:8080/dashboard), you should just see a blank page if you're not signed in and/or you don't have the proper permissions.

There's one more thing you can do from a UI perspective to prevent that blank page where the data didn't load because you were unauthorized.

Open up `client/src/router/index.js` and modify the `/dashboard` route like so:

``` js  
{
  path: '/dashboard',
  name: 'dashboard',
  component: () => import('../views/Dashboard.vue'),
  beforeEnter: authGuard  // 👈 NEW
},
```

The [`beforeEnter` Vue route option](https://router.vuejs.org/api/#router-construction-options) allows you to run some code before the route can be accessed. In this case, you'll be running the Auth0 provided `authGuard`, which checks if the user has an access token. If they don't, they'll be redirected to the login page.

Keep in mind that this is just for UI purposes to prevent that blank page and let the user know that if they want to access it, they should sign in first. If you were still serving the data to the frontend without the backend access check, the user could just click "View Source" on the page and easily find the data. That's why it's extremely important to **always protect the data from the backend**, as you've done already.

If you haven't signed up yet, go ahead and do that now.

## Create an Admin User

The next problem is that you don't have the required permission to view this page. You can automatically assign permissions to a user from the [Auth0 dashboard](https://manage.auth0.com/dashboard/) by creating a role and then assigning permissions to that role.

Once you're in the dashboard, click on "**Users & Roles**" and then select "**Roles**". Click on the red "**+ Create Role**" button. For name, type "vue-dash-admin" and for description "Vue dashboard admin" and then click "**Create**". Now click on the newly created role, and you'll see a "**Permissions**" tab. Click on that and then press the blue "**Add Permissions**" button. Select your Express API from the dropdown, and then check the `manage:users` permission. 

Click "**Assign Permissions**", and you should see your Vue Express API in the dropdown. Select this, check the `manage:users` permission, and click "**Save**". Now any user that receives the "vue-dash-admin" role will also be granted the `manage:users` permission.

Go back to the "**Users**" page and find the user account that you used to sign into the Vue Express application. Click on it, and you'll see a "**Roles**" tab. Click on "**Assign Roles**" and then select the new `vue-dash-admin` role you just created and press "**Assign**".

![Auth0 dashboard user permissions](https://images.ctfassets.net/23aumh6u8s0i/2bJ26pb4ZFJtPH74viXFZq/a6c60125d794035eb5b41b998f2e7426/auth0-dashboard-user-role)

## Enable RBAC Settings

Finally, go back to the Vue Express API page in the Auth0 dashboard and click on "**Settings**". Then scroll down to where it says "**RBAC Settings**". Click the switches next to "**Enable RBAC**" and "**Add Permissions in the Access Token**", and then click "**Save**".

This will tell Auth0 that the **API is expecting these permissions in the access token** for certain authorized users.

## Test it out

Now, go back to your Vue dashboard, [`http://localhost:8080/dashboard`](http://localhost:8080/dashboard), and sign out. Sign back in with the user you assigned the `manage:users` permission to so that you get a fresh token. You should now be able to see your list of users again!

If you're curious, the access token contains this user information:

``` js  
user:
{ 
  iss: 'https://demo-apps.auth0.com/',
  sub: 'google-oauth2|xxx',
  aud:
  [ 'https://vue-express-api.com',
    'https://demo-apps.auth0.com/userinfo' ],
  iat: 1579881686,
  exp: 1579968086,
  azp: 'xxxxxx', // authorized party id
  scope: 'openid profile email',
  permissions: [ 'manage:users' ] 
} 
```

As you can see, the access token holds the `manage:users` permission, which tells your Express API that the user is authorized to make a request to the `/users` endpoint. If you'd like to see your own access token, add `console.log(req.user)` inside `app.get('users')` in `server/server.js`, as shown below:

``` js  
// server/server.js
// ...
app.get('/users', checkJwt, checkPermissions, (req, res) => {
  managementAPI
    .getUsers()
    .then(function(users) {
      console.log(req.user); // 👈 NEW
      res.send(users);
    })
    .catch(function(err) {
      console.log(err);
    });
});
```

Open your console and refresh the dashboard page and you'll see the contents of your access token.

To test out the delete button, make sure you **first create a test user** so that you don't delete your own account. You can create a new user in the [Auth0 dashboard](https://manage.auth0.com/dashboard) under "Users & Roles".

## Summary

And that's it! 🙌

As you can see, **almost anything you can do in the Auth0 dashboard, you can also do with the Management API**.

You covered a lot here, so congratulations if you made it through! Just to recap, here's what you learned:

- Set up Auth0 authentication in a Vue and Express app
- Authorize your Express app to use the Auth0 Management API
- Learn how to get a Management API token from Auth0
- Learn about client credentials grant
- Make a request to the Auth0 Management API
- Protect your Express endpoints
- Authorize your Vue client to make a request to your Express API
- Add roles and permissions to users
- Display data in your Vue app
- Delete users from your Vue dashboard

Now that you've gotten through the tough part, **getting a Management API token**, feel free to look through the [Auth0 Node Management Client documentation here](https://auth0.github.io/node-auth0/module-management.ManagementClient.html) and see if you can expand your Vue Express dashboard to perform more operations on users, such as updating and creating.

Don't forget to **add the proper permissions** to your application in the Auth0 dashboard if you decide to extend it! You can find the [Auth0 Management API docs here](https://auth0.com/docs/api/management/v2) in case you want to query the endpoints directly. Let me know if you need any guidance in the comments below, and thanks for reading!

<include src="tutorial/FeedbackButton" communityTopic="53302"/>


Build an Admin Dashboard with Express and Vue: Adding User Authorization



The **Auth0 dashboard** has extensive tools that you can use to manage your application's authentication and authorization. You can create users, delete users, assign roles to users, ban IPs, and much more. While it's great to have the option to manage users straight from the dashboard, you might sometimes run into a scenario where you need to have that control straight from your own application.

Consider this use case. You're building a blogging platform for a client, and you're using Auth0 as an identity solution. The client haquos a few employees that will need full admin access to the blog. They'll have the ability to make updates to any users that sign up, ban users, view user data, and more.

Here's the caveat: the client doesn't want her employees to have to sign into another platform to do this. She wants you to build a dashboard on the blogging platform that will give administrators the capability to manage users straight from the blogging application. Lucky for you, you can do all of this using the [Auth0 Management API](https://auth0.com/docs/api/management/v2)! 

In this article, you'll learn how to **build a simple user management dashboard** using Vue.js, Node.js, and [Auth0](https://auth0.com). You'll be using the Auth0 Management API to pull all of your application's users into your Vue Express application. You'll also add a delete button so that you can delete users straight from your own dashboard. You can check out the final [User Management Dashboard code here](https://github.com/auth0-blog/express-vue-management-api).

![Auth0 user dashboard Management API](https://images.ctfassets.net/23aumh6u8s0i/6tjQ9rvSCgOcZ9MIrd9dCx/61d999a28e841ab4aac8a07c547226d0/auth0-user-management-api-dashboard)

## Getting Started

To keep this focused on user management, you're going to be building the dashboard from an existing application that was built in two previous tutorials: [Beginner Vue.js Login Tutorial](https://auth0.com/blog/beginner-vuejs-tutorial-with-user-login/) and [Making HTTP Requests with Vue and Express](https://auth0.com/blog/how-to-make-secure-http-requests-with-vue-and-express/).

You don't need to read those to follow along with this tutorial, but you should be familiar with Vue and Express. If not, those two tutorials will be a great starting point, even for a beginner!

To begin, clone the [Vue and Express Events app repository](https://github.com/auth0-blog/vue-express-auth) and follow the instructions in the README to get everything set up. You'll also need to <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for a free Auth0 account</a>. The [Auth0 configuration details](https://github.com/auth0-blog/vue-express-auth#configuring-auth0) are also in the README.

Without further ado, let's dive into the Management API!

## Using the Management API

This will be covered step by step, but here's a quick overview of what you'll need to do to get access to the Auth0 Management API:

* Create a Machine-to-Machine Application in the Auth0 dashboard
* Connect it to your Express API
* Get a short-lived access token for production

[In the Auth0 dashboard](https://manage.auth0.com/dashboard/), click on "APIs" in the left menu and then select "Auth0 Management API". This is a pre-configured Auth0 system API that you can use to connect to the Management API.

To use the Management API, you first need to get an access token called the *Auth0 Management API Token*. This token is used to **authorize your application to access the Management API**. As you'll see soon, whenever you make a request to the API, you'll send this token along with it, and the Auth0 server will check that it's valid.

You can get this token straight from the dashboard so that you can immediately experiment with the API. This method is for testing only. Let's play around with the API this way first, and then you'll generate an API access token on the fly from your own application afterward.

## Get a Token from the Dashboard

Make sure you're still on the Auth0 Management API page and click on "**API Explorer**" from there. Next, click the blue button that says "**CREATE & AUTHORIZE TEST APPLICATION**". A test access token will then be generated for you. Copy this token and head to the [Auth0 Management API Explorer](https://auth0.com/docs/api/management/v2). In the top left corner, you should see a button that says "**SET API TOKEN**." Click on this, paste your token in, and click "Set Token."

![Auth0 Management API explorer](https://images.ctfassets.net/23aumh6u8s0i/5DOSy4hJXfauYKGrRojrbv/31ba756ff4cdf854c3f9c7a848c755cc/auth0-api-explorer)

The API explorer provides a convenient way to test out any API calls that you might need to use once you start working on your application. You can scroll through the API Reference in the left menu to see everything you can do with the Management API.

Go ahead and test out one of the requests you'll be making in this tutorial. Scroll down to [List or search users](https://auth0.com/docs/api/management/v2#!/Users/get_users). You'll see some documentation and optional parameters that you can use to build your request. Just leave all of these blank for now and press the blue button that says "Try" (you'll have to scroll down a bit).

The response will be an array of objects, where each object contains information about an individual user such as name, email, number of logins, when their account was created, and more.

![Auth0 management API explorer - get all users](https://images.ctfassets.net/23aumh6u8s0i/2wnwGQAykgydsRq9lgi8WT/4c7f5a42fa1c3049ed5587ab1ee85620/auth0-management-api-explorer)

Feel free to experiment with the Management API here. You can always get a new token from the dashboard whenever yours expires.

## Setup to Get a Token Programmatically

Since the point of this tutorial is to streamline some of this user management process, you're going to want to be able to **automatically generate** a new Auth0 Management API Token straight from your application.

To do this, you need to connect your client application to the Auth0 Management API in the dashboard so that it knows who it's issuing an access token to. In this case, **the client application is your Express API**.

> Note: If you're scratching your head wondering how an Express application is the client, don't worry, you're not alone. It seems strange, but Express is the client in relation to the Auth0 Management API. Your Express application will be the one requesting access to a resource from the Management API.

Make sure you're still on the Auth0 Management API page [in the Auth0 dashboard](https://manage.auth0.com/dashboard/) and click on "**Machine to Machine Applications**". Click on the switch next to "**Vue Express API**" or whatever you named your Express API when you set it up in Auth0 from the [Vue and Express Events app repository README](https://github.com/auth0-blog/vue-express-auth). It should now be green and say "Authorized."

![Auth0 Management API authorized client](https://images.ctfassets.net/23aumh6u8s0i/3bnn4TcXg4JJ6Ti42f4ymi/1545602b9f43d8c6dcfafda536730d27/auth0-management-api-authorized)

You'll also need to add permissions to this application, so go ahead and handle that now. Click on the down arrow `V` next to the authorized switch. For the purpose of this application, select `read:users`, `delete:users`, and `read:user_idp_tokens` and then click "Update".

* `read:users` &mdash; Read your Auth0 application's users
* `delete:users` &mdash; Delete your Auth0 application's users
* `read:user_idp_tokens` &mdash; Read the [identity provider](https://auth0.com/docs/identityproviders) access token

If you scroll back up, you'll see a tab titled "**Test**" next to "**Machine to Machine Applications**". Click on "**Test**", and you should see your API in the dropdown right underneath "Asking Auth0 for tokens from my application". Select the "**Vue Express API**" and then click on "**Node.JS**" underneath it. This will give you the code for the API call that will allow the Express API to request a token from the Auth0 Management API.

Leave this page open, as you'll be using it in the next section.

<include src="tutorial/NextButton" nextPart="build-an-admin-dashboard-with-express-and-vue-creating-the-backend/" completedMessage="I've set up my application in the Auth0 dashboard"/>

<include src="tutorial/IssueButton" communityTopic="53302"/>


Build an Admin Dashboard with Express and Vue



<details>
<summary>Starting from this chapter?</summary>

**Setting up**

Clone the application starter repo and check out the `creating-the-backend` branch:

``` bash  
git clone git@github.com:auth0-blog/express-vue-management-api.git --branch creating-the-backend
```

Install the dependencies for both the client and server:

``` bash  
cd server
npm install
cd ../client
npm install
```

**Configure Auth0**

Follow the Auth0 Configuration directions in the [project README of the starter Vue and Express application](https://github.com/auth0-blog/vue-express-auth#configuring-auth0).

**Configure Management API**

In the [Auth0 dashboard](https://manage.auth0.com/dashboard), click on "APIs" in the left menu and then select "Auth0 Management API". From there, select "Machine to Machine Applications" and find the "Vue Express API" you just created. Click the switch next to it so that it says "Authorized".

![Auth0 authorized API](https://images.ctfassets.net/23aumh6u8s0i/3bnn4TcXg4JJ6Ti42f4ymi/1545602b9f43d8c6dcfafda536730d27/auth0-management-api-authorized)

Next, add permissions to the application. Click on the down arrow V next to the authorized switch. Select `read:users`, `delete:users`, and `read:user_idp_tokens` and then click "Update".

Create the `.env` file in the root of the `server` directory:

``` js  
AUTH0_DOMAIN = your-domain.auth0.com
AUTH0_AUDIENCE = https://your-api-audience.com
CLIENT_ID = yourclientid
CLIENT_SECRET = yourclientsecret
```

To find your values, go to the [Auth0 dashboard](https://manage.auth0.com/dashboard) and click:

"APIs" > "Auth0 Management API" > "Test"

Select the Express API from the dropdown then click "Node.JS". You'll find the values for `CLIENT_ID` AND `CLIENT_SECRET` in the resulting code.

`AUTH0_DOMAIN` and `AUTHO_AUDIENCE` can be found by clicking on "APIs" and then selecting the Vue Express API. Then click on "Quick Start" and select "Node.js". You'll see a value for audience, which you can paste directly into AUTH0_AUDIENCE and then another value for issuer. Copy this and paste it into AUTH0_DOMAIN, but leave off the `https://` and the trailing `/` at the end.

**Test it**

Start the Vue app:

``` bash  
cd client
npm run serve
```

Start the Express app:

``` bash  
cd server
npm start
```

Navigate to [http://localhost:8000/users](http://localhost:8000/users) to see an array all of your users from the Express `/users` endpoint.

View the dashboard at: [http://localhost:8080/dashboard](http://localhost:8080/dashboard)

</details>

## Creating the Dashboard with Vue

Here's what needs to be done on the Vue side:

* Create a dashboard route
* Create a new dashboard component
* Create the user service to connect to the Express API
* Make a `GET` request to the Express API's `/users` route
* Loop over and display the users
* Create a delete button and delete method
* Add the delete method to the user service that makes a request to the Express API's `/users/:id/delete` route
* Pass the user's access token along with their Express API requests
* Restrict the route so that unauthenticated users will be kicked to the login screen

I'll go over each step here, but if you'd like a more in-depth explanation about making HTTP requests in Vue, I'd recommend going back and reading through the original article that this application is based on, [Making HTTP Requests with Vue and Express](https://auth0.com/blog/how-to-make-secure-http-requests-with-vue-and-express/). 

If you haven't already, you can start the Vue application by navigating to the `client` directory in the terminal and running:

``` bash  
npm run serve
```

You can view it at [http://localhost:8080](http://localhost:8080)

## Add the Dashboard Route

First, go ahead and create the `/dashboard` route, which is where the user list will be displayed.

Open up `client/src/router/index.js` and paste the following in as the last element in the `routes` array:

``` js  
{
    path: '/dashboard',
    name: 'dashboard',
    component: () => import('../views/Dashboard.vue')
}
```

## Create the Dashboard Component

You'll notice that the `/dashboard` route is using the `Dashboard.vue` component. This doesn't exist yet, so go ahead and create it now.

Under `client/src/views`, create a new file called `Dashboard.vue` and paste in the following:

``` js  

<template>
<div class="container">
  <h2 class="title is-size-3 has-text-centered">Welcome to your dashboard</h2>
  <div class="columns" v-if="message">
    <div class="column is-one-quarter is-offset-8">
      <div class="notification is-success">
        {{ message }}
      </div>
    </div>
  </div>
  <div class="columns is-multiline has-text-centered">
    <div v-for="user in users" :user="user" :key="user.id" class="column is-one-quarter">
      <img :src="user.picture" :alt="user.name" style="width:200px;margin-left:auto;margin-right:auto;"/>
      <h3 class="is-size-6">Name: {{ user.name }}</h3>
      <h3 class="is-size-6">Email: {{ user.email }}</h3>
      <h3 class="is-size-6">Last login: {{ user.last_login }}</h3>
      <h3 class="is-size-6">Login count: {{ user.logins_count }}</h3>
      <button @click="deleteUser(user.user_id)" class="button is-medium is-danger">Delete me 😵</button>
    </div>
  </div>
</div>
</template>
<script>
import UserService from '@/services/UserService.js';
export default {
    name: "Dashboard",
    data() {
    return {
      users: [],
      message: ''
    };
  },
  created() {
    this.getUserData(); // call getEventData() when the instance is created
  },
  methods: {
    async getUserData() {
      // Pass the access token to the getUsers service
      UserService.getUsers()
      .then(
        (users => {
          this.$set(this, "users", users);
        }).bind(this)
      );
    },
    async deleteUser(deleteId) {
      // Pass specified id to the deleteUser service
      UserService.deleteUser(deleteId)
      .then(
        (response => {
          this.message = response; 
          this.getUserData(); // get refreshed users
        })
      );
    }
  }
}
</script>
<style lang="scss" scoped>
  .notification {
    position: fixed;
    top: 800px;
    right: 40px;
  }
  .button {
    margin-top: 15px;
  }
</style>

```

In the script section, you're first importing the `UserService`. This is what your Vue application will use to connect to the Express API defined in the `server` directory. The Express API is responsible for getting the data from the Management API.

> 🧠 Your Vue client cannot reach out to the Management API directly because it would need an access token to do that, and as you saw earlier, that would require the client (Vue) to pass the client secret on the frontend, which isn't secure.

So, instead, the **Express API handles the connection** with the Management API. The Vue application then makes a request to the Express API using the `UserService` and receives the user information that the Express API passes back to it.

Of course, you wouldn't want just *anybody* to be able to access this user information. This is why the **request to the Express API from the Vue client must be authorized**. With the current implementation, anyone will be able to access the Express API endpoints to obtain the list of users and delete a user. Sit tight for now, and you'll be addressing that in an upcoming section.

The next important thing to note here are the 2 methods: `getUserData()` and `deleteUser(deleteId)`. The first method is called when the Dashboard instance is created. It's going to call the `getUsers()` method on the `UserService` and then set the result to the `users` array (defined under `data`). The next method will be called when the user clicks on a "Delete me" button underneath a user. It will send the selected user's `user_id` through to the `UserService.deleteUser()` method as a parameter.

If you glance back up now at the template section, you'll see where that `users` array comes into play. You're looping over it to display each individual user's avatar, name, email, last login date, and login count.

Finally, there's a `message` variable that will let us know that a user has been deleted.

Now, the `UserService` doesn't exist, so none of this is going to work yet. Go ahead and create it now.

## Create the User Service

Create a new file called `UserService.js` under `client/src/services` and paste in the following:

``` js  

import axios from "axios"
export default {
  async getUsers() {
    let res = await axios.get("http://localhost:8000/users");
    console.log(res.data);
    return res.data;
  },
  async deleteUser(id) {
    let res = await axios.get(`http://localhost:8000/users/${id}/delete`);
    return res.data;
  }
}

```

This allows the Vue application to make a `GET` request to the Express API using [axios, a promise-based HTTP client](https://github.com/axios/axios).

You're calling the `/users` and `users/${id}/delete` routes that you built earlier in Express. The `/users` route is the one that returns the user information from the Management API.

So when the Vue application makes a `GET` request to the Express `/users` route, Express reaches out to the Management API and makes a request for the list of users. If the access token that the Express API presents is valid, then the Management API returns the users. Consequently, the Express API will then return that data to the requesting Vue application.

Again, it's important to verify that the Vue application is allowed to access this information. **Whether or not it's allowed to access it is between the Express API and the Vue application, not the Management API**. Currently, there's nothing in place to check that the Vue application is allowed to make this request to the Express API. You'll see how to implement this in the next section.

For now, make sure your Vue application and Express app are both still running in the terminal:

**Vue application:**

``` bash  
npm run serve
```

**Express application:**

``` bash  
npm start
```

Head to [`http://localhost:8080/dashboard`](http://localhost:8080/dashboard), and you should now see your shiny new dashboard with all of your user's avatars and information displayed.

> 🚨 Resist the urge to click the "Delete" button on the accounts you want to keep! I recommend creating test user accounts through the Auth0 dashboard when you want to try out the delete button.

![Vue Express Auth0 management API user dashboard](https://images.ctfassets.net/23aumh6u8s0i/6tjQ9rvSCgOcZ9MIrd9dCx/61d999a28e841ab4aac8a07c547226d0/auth0-user-management-api-dashboard)

<include src="tutorial/NextButton" nextPart="build-an-admin-dashboard-with-express-and-vue-adding-user-authorization/" completedMessage="I've created the Vue dashboard"/>

<include src="tutorial/IssueButton" communityTopic="53302"/>


"management-api"