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 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, last 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 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