Docs

JavaScript: Calling an API

View on Github

JavaScript: Calling an API

This tutorial demonstrates how to make API calls for protected resources on your server. We recommend you to Log in to follow this quickstart with examples configured for your account.

I want to integrate with my app

15 minutes
  1. Create an API
  2. Create a Backend API
  3. Calling the API
Or

I want to explore a sample app

2 minutes

Get a sample configured with your account settings or check it out on Github.

View on Github

Most single-page apps use resources from data APIs. You may want to restrict access to those resources, so that only authenticated users with sufficient privileges can access them. Auth0 lets you manage access to these resources using API Authorization.

This tutorial shows you how to access protected resources in your API.

This tutorial does not show you how to add protection to your API. Read the Backend/API quickstart documentation for instructions on how to protect your API.

Create an API

In the APIs section of the Auth0 dashboard, click Create API. Provide a name and an identifier for your API. You will use the identifier later when you're configuring your Javascript Auth0 application instance. For Signing Algorithm, select RS256.

Create API

Create a Backend API

In this section, you will modify the ExpressJS that you created in part 1 so that it supports a new endpoint. This endpoint will require a valid access token to be sent in the Authorization header for the call to be successful.

Add middleware to the backend

To begin, let's install some NPM packages that will be used to validate incoming tokens to the server. From the terminal:

Next, open server.js and bring in these libraries as imports at the top of the file. Also bring in the auth_config.json file so that the script can get access to the authentication credentials that have been configured:

  • express-jwt - validates JWTs from the authorization header and sets the req.user object
  • jwks-rsa - downloads RSA signing keys from a JSON Web Key Set (JWKS) endpoint

Then add a call to jwt(), which creates the middleware needed in order to validate and parse incoming access tokens. This should go after the require statements but before any routes are defined in your app:

This code configures the express-jwt middleware with the settings that relate to your Auth0 application. It uses a JWKS endpoint to download the RSA public key, which it uses to verify the signatures of incoming access tokens.

Next, open the auth_config.json file and modify the data so that the audience appears as a key within the JSON, using the value that you just used when creating the API:

As auth_config.json is served publicly, this file should never contain sensitive information such as passwords and client secrets.

The values for domain and clientId should have already been specified as part of the Login tutorial. They should point to the Domain and Client ID values for your Auth0 app respectively.

Add a protected endpoint

The last thing to do on the server side is to add an API endpoint that requires an access token to be provided for the call to succeed. This endpoint will use the middleware that you created earlier in the tutorial to provide that protection in a scalable way.

Open server.js and add a new route for /api/external above the other routes that returns some JSON:

Note that checkJwt is used as the second argument here. This causes checkJwt to be executed before the main route handler, and will reject the call and return a 401 response if:

  • there is no access token present in the Authorization header,
  • or the token itself is not valid

Finally, add an error handler so that a JSON response is returned from your API in the event of a missing or invalid token:

At the end, your server.js file will look something like the following:

Test the API

With this in place, run the application using npm run dev. In another terminal window, use the curl tool to make a request to this API endpoint and observe the results:

You should find that a 401 Unauthorized result is returned, because it requires a valid access token:

Calling the API

Now you can turn your attention to the front-end application. You will update the application to provide a button to call a function which will in turn call the API that you created in the previous section.

Open index.html and add a new button that will invoke the API call, as well as a pre element with an ID of api-call-result to show the result of the API call in the browser:

Next, open public/js/app.js. Configure the auth0 client object to specify the audience value that was added earlier to the auth_config.json file:

Add a new function called callApi to app.js, with the following content:

Finally, find the updateUI function within app.js and modify it so that the button for calling the API is enabled when the user logs in:

Now, open the browser in the application at http://localhost:3000. If the application has been stopped, run it again from the terminal using npm run dev.

When the application starts, log in. Then, press the Call API button to make a request to the API and put the results on the screen. You should find that the result from the server is displayed on the page.

Use Auth0 for FREE