Instructions for

On this page

Protect your API endpoints

Add authorization using Okta to protect your APIs. When you finish, you have a secure REST API application that validates incoming requests.


Learning outcomes

  • Add Okta authorization (opens new window) to your API endpoints.
  • Add dependencies and configure your API.
  • Create an anonymous endpoint and restricted endpoint.
  • Require authorization on protected routes.
  • Make an HTTP request with and without a valid access token.

What you need

A Custom Authorization Server to create and apply authorization policies to protect your APIs

Note: Okta's Developer Edition makes most key developer features available by default for testing purposes. Okta's API Access Management product — a requirement to use Custom Authorization Servers — is an optional add-on in production environments.

Sample code


Set up Okta

Set up your Okta org. The CLI is the quickest way to work with your Okta org, so we recommend using it for the first few steps. If you don't want to install the CLI, you can manually sign up for an org (opens new window) instead. We provide non-CLI instructions along with the CLI steps below.

  1. Install the Okta command-line interface: Okta CLI (opens new window).

  2. If you don't already have a free Okta developer account, create one by entering okta register on the command line.

  3. Make a note of the Okta Domain as you need that later.

  4. IMPORTANT: Set the password for your Okta developer org by opening the link that's shown after your domain is registered. Look for output similar to this:

    Your Okta Domain: https://dev-xxxxxxx.okta.com
    To set your password open this link:
    https://dev-xxxxxxx.okta.com/welcome/xrqyNKPCZcvxL1ouKUoh
    

    Note: If you don't receive the confirmation email sent as part of the creation process, check your spam filters for an email from noreply@okta.com

  5. Connect to your Okta developer org if you didn't create one in the last step (successfully creating an Okta org also signs you in) by running the following command. You need the URL of your org — which is your Okta domain with https:// prepended — and an API/access token:

    okta login
    

Create a REST API

Create a new application with a simple API endpoint to add authorization to.

Create a new API project

Include the dependencies

Configure your API

You need to configure the API with some information about the authorization server used by your Okta organization.

Note: This tutorial uses the default Custom Authorization Server to secure your protected API. You can create your own Custom Authorization Server for this purpose. In either case, you need an appropriate license to use the Custom Authorization Server in production.

Things you need

Our project uses information from the Okta organization we created earlier to configure communication with the API. You can find these values in the API section of the Admin Console: Select Security > API from the main menu.

There are three pieces of information you may need, depending on the platform you are using:

  • Audience: api://default by default

  • Authorization Server Name: default

  • Okta Domain: Found in the global header located in the upper-right corner of the dashboard. Click the down arrow next to your email address and in the dropdown box that appears, move your pointer over the domain name. Click the Copy to clipboard icon that appears to copy the domain.

    Note: Your Okta domain is different from your admin domain. Your Okta domain doesn't include -admin, for example, https://dev-133337.okta.com.

Create your REST endpoints

Create new REST endpoints in your application that cover two different use cases:

  • api/whoami — A protected endpoint (access-restricted API)
  • api/hello — An endpoint that anonymous users can access (unsecured API)

Configure required authentication

In many APIs, all of the endpoints require authorization. In others, there may be a mix of protected and unprotected (anonymous) endpoints. These examples show you how to do both.

Require authorization for everything

Allow anonymous access for specific routes

If you have endpoints that need to be accessed without any authorization, instead of securing the entire API like the previous section, you can configure access per route.

Configure CORS if necessary

Configuring Cross-Origin Resource Sharing (CORS) is only required if the API is being called from a browser app hosted on a different domain. For example, if you are hosting a single-page JavaScript app at example.com, which consumes an API endpoint hosted on api.example.com, you need to enable CORS.

Consume your secure API endpoints

Test your APIs with an access token that is sent to your endpoint for validation.

Use an access token with your API endpoint

In order for someone to make a request to your API, they need an access token. How an access token is obtained depends on the client making the request.

If your API is consumed from another machine or service (instead of users), you can follow the Client Credentials flow to create an access token. See Sign users in to your single-page app using the redirect model or Sign users in to your mobile app using the redirect model for instructions on how to retrieve an access token in those types of app.

Note: The information contained within an access token varies depending on the type of flow used to create it. For example, the Client Credentials flow doesn't contain any claims with user information such as a user ID or email.

If you are using Postman and the Client Credentials flow, you can use an API call of the form https://${yourOktaDomain}/oauth2/default/v1/token, with an Authorization header set, and you will get a response containing an access token.

Postman showing a token request post response including an access token

Copy the value in the access_token object field and use it for testing your API in the next step.

Run your API

Start your server to get your API running.

Leave your API running locally (or deployed if desired) and proceed to the next step.

Send a request to your API endpoint using Postman

After your API is running locally, you need to test it. Using a tool like Postman or cURL, call your API endpoints to see the responses with and without your token.

The expected results are as follows, provided you followed the instructions in the Allow anonymous access for specific routes section:

  • api/whoami — 401 response without a valid token, 200 response with a valid token.
  • api/hello — response with or without a valid token, due to anonymous access.

If you are using Postman, your GET call and response should look something like this:

Postman showing a get request to the protected endpoint with a token, and a resulting 200 response

Next steps