Represent Multiple APIs Using a Single Logical API in Auth0
If you have multiple distinct API implementations that are all logically a part of the same API, you can simplify your authorization process by representing them with a single logical API in the Auth0 Dashboard. Doing this allows you to implement just one authorization flow, while still controlling access to the individual APIs by assigning the appropriate scopes.
This tutorial explains how to use and represent multiple APIs as a single Resource Server in Auth0. As a learning tool, we provide a sample application that you can follow along with as you read.
The Sample Application
The sample application uses a microservices architecture and contains:
- 1 Single-Page Application (SPA)
- 2 APIs (services), called
We will represent the two APIs using just one Auth0 API called
Organizer Service. We will then create two namespaced scopes to demonstrate how you can use the Implicit Flow to access the
contacts APIs from the SPA.
Before beginning this tutorial:
- Register your Application with Auth0
- Select an Application Type of Single-Page App.
- Add Allowed Callback URLs of
- Download the sample application, so you can follow along as you read. Please see the
READMEfor additional information on setting up the sample on your local environment.
- Enable a Connection for your Application: Configure a source of users for your new application.
- Create a test user: Associate a test user with your new connection.
- Register a logical API in Auth0: Register a single logical API to represent your multiple APIs.
- Configure scopes for the logical API: Create the scopes that will allow the logical API to represent your multiple APIs.
- Grant access to the logical API: Configure the login link in your sample application, initiate the authorization flow, and extract the Access Token to be used to call your multiple APIs. Optional: Implement Single Logout (SLO) or Single Sign-on (SSO)
Enable a connection for your Application
You will need a source of users for your newly-registered application, so you will need to configure a Connection. For the purpose of this sample, we'll create a simple Database Connection that asks only for the user's email address and a password.
- Navigate to the Auth0 Dashboard, and click on Connections > Database in the left-hand nav. Click Create DB Connection.
- The Create DB Connection window will open. Provide a Name for your Connection, and click Create to proceed.
- Click the Applications tab, and enable the Connection.
Create a test user
Since you're working with a newly-created Connection, there won't be any users associated with it. Before we can test the sample application's login process, we'll need to create and associate a user with the Connection.
- Navigate to the Auth0 Dashboard, and click on Users in the left-hand nav. Click Create User.
- Provide the requested information about the new user (email address and password), and select your newly-created Connection.
- Click Save.
Register a logical API in Auth0
Register a single logical API that you will use to represent the multiple APIs contained within the sample application.
- When prompted, provide a name and identifier for the new API, and choose the signing algorithm for the tokens obtained for this API.
For the purpose of this sample, we'll call our API
Organizer Service and set its unique identifier to
organize. By default, the signing algorithm for the tokens obtained for this API is RS256, which we will leave as is.
When finished, click Create.
Configure scopes for the logical API
To allow the logical API to represent the APIs included within the sample application, you will need to create the proper scopes.
Scopes allow you to define which API actions will be accessible to calling applications. One scope will represent one API/action combination.
For example, if you want calling applications to be able to
delete from one API called
samples and another one called
examples, you would need to create the following permissions:
You can think of each one as a microservice.
- In your newly-created logical API, click the Scopes (or Permissions) tab.
- Add two scopes:
Save your changes.
Grant access to the logical API
You are now ready to provide access to your APIs by allowing the logical API to obtain Access Tokens. By including the necessary scopes, you can control an application's access to the APIs represented by the logical API.
The rest of this article covers use of the Implicit Flow to reflect the sample. However, you can use whichever flow best suits your needs. For example:
- If you have a Machine-to-Machine Application, you can authorize it to request Access Tokens for your API by executing a Client Credentials Flow.
- If you are building a Native App, you can implement the Authorization Code Flow with Proof Key for Code Exchange (PKCE).
For a full list of available Authorization flows, see API Authorization.
- The user clicks Login within the SPA, and the app redirects the user to the Auth0 Authorization Server (
- Your Auth0 Authorization Server redirects the user to the login page, where the user authenticates using one of the configured login options.
- If this is the first time the user has been through this flow, they see a consent prompt listing the permissions Auth0 will give to the SPA. In this case, the user is asked to consent to the app reading their contacts and calendar.
In our sample, after you successfully log in, you will see buttons that allow you to call either of your APIs using the Access Token obtained from the logical API.
Implement Single Logout (SLO) or Single Sign-on (SSO)
In some multi-application scenarios, where Single Logout is desired (a user logging out of one application needs to be logged out of other applications), an application can be set up to periodically poll Auth0 using
checkSession() to see if a session exists. If the session does not exist, you can then log the user out of the application. The same polling method can be used to implement silent authentication for a Single Sign-on (SSO) scenario.
The poll interval between checks to
checkSession() should be at least 15 minutes between calls to avoid any issues in the future with rate limiting of this call.