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.

Note: The org authorization server isn't supported for Web APIs because your application can't validate the access token issued by an org authorization server. This guide uses the default custom authorization server to secure your protected API. You can create your own custom authorization server for this guide. The Okta Developer Edition (opens new window) makes most key developer features available by default for testing purposes. The Okta API Access Management product — a requirement to use custom authorization servers — is an optional add-on in production environments.


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 developer account and Okta org. The Okta command-line interface (CLI) is the quickest way to do this. Alternatively, you can manually sign up for a developer account (opens new window).

  1. Install Okta CLI (opens new window).
  2. If you don't already have a free Okta developer account:
    1. Open your terminal.

    2. Run okta register, and enter your first name, family name, email address, and country.

    3. Click or tap Activate in the account activation email that is sent to the email address that you gave.

      Tip: 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

    4. Find your new domain and a link to set your password in the email:

      Your Okta Domain: https://dev-xxxxxxx.okta.com
      To set your password open this link:
      https://dev-xxxxxxx.okta.com/welcome/xrqyNKPCZcvxL1ouKUoh
      
    5. Set the password for your org by opening the link and following the instructions. Your Okta domain is returned, similar to the following:

      New Okta Account created!
      Your Okta Domain: https://dev-xxxxxxx.okta.com
      
    6. Make a note of your Okta domain. Use it wherever ${yourOktaDomain} appears in this guide.

Note: If you're using an existing org, verify that API Access Management is enabled: Open your Admin Console, go to Security > API, and verify that an Authorization Servers tab is present. If not, choose one of the following:

  • Create a developer account and org with Okta CLI.
  • Contact your support team to enable the feature in your org.

All accounts created with Okta CLI are developer accounts and have API Access Management enabled by default.

Create a REST API

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

Create an API project

Include the dependencies

Configure your API

Configure the API with some information about the authorization server used by your Okta org.

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

Use information from the Okta org created earlier to configure communication with the API. Find these values in the API section of the Admin Console: Select Security > API from the main menu.

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

  • Audience: api://default by default

  • Authorization Server Name: default

  • Okta Domain: Locate by clicking your username in the upper-right corner of the Admin Console. The domain appears in the dropdown menu.

    Note: Your Okta domain is different from your admin domain. Your Okta domain doesn't include -admin, for example, https://dev-133337.okta.com rather than https://dev-133337-admin.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 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

To allow a mix of protected and unprotected (anonymous) endpoints, configure access on a per route basis.

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're 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

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:

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're using Postman and the Client Credentials flow, call https://${yourOktaDomain}/oauth2/default/v1/token, with an Authorization header set, to receive an access token.

Postman showing a response to a token request 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 with 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're 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