Is it easy or difficult to use our developer documentation? Let us know in this short survey ↗

Instructions for

On this page

Protect your API endpoints

Add a layer of authorization to your web services with Okta API Access Management.


Learning outcomes

  • Configure a web API to use Okta
  • Define which endpoints require authorization and which don't
  • Enable Cross-Origin Resource Sharing (CORS) for the API
  • Test the API is secure

What you need

Sample code

Note: Several standalone tools can send requests to APIs and allow you to inspect the responses. Our documentation uses Postman and offers Postman Collections to test its APIs more efficiently with a GUI. It also includes HTTP requests as text for those who prefer to use a terminal utility such as cURL (opens new window).


Overview

Background services and third-party APIs accessing your own APIs require the same level of authentication and authorization (opens new window) as users accessing your web apps. However, a machine-to-machine sign-in flow should be silent and require no human user interaction. Use Okta to grant the correct level of access to your APIs on your behalf.

This quickstart contains the following tasks:

  1. Check that API Access Management is enabled
  2. Create and configure a new web API to use Okta
  3. Configure different levels of access for different endpoints
  4. Enable CORS for your API
  5. Test your API is secure

Tip: You need your Okta org domain to follow this tutorial. It looks like dev-123456.okta.com. See Find your Okta domain. Where you see {yourOktaDomain} in this guide, replace it with your Okta domain.

Note: For a similar use case where Okta secures a machine-to-machine sign-in flow between a background service app and the Okta APIs, rather than a service app and your own API, see Implement OAuth for Okta with a service app

Check that API Access Management is enabled

API Access Management (API AM) is the feature in your org that allows Okta to secure your APIs. When enabled, API AM allows you to create an authorization server that establishes a security boundary for your APIs. All new developer orgs have API AM enabled by default, but it’s optional for production orgs. Check that it’s enabled in your org as follows:

  1. Open the Admin Console for your org.
    1. Sign in to your Okta organization (opens new window) with your administrator account.
    2. Click Admin in the upper-right corner of the page.
  2. Go to Security > API to view the API AM area.

If no Authorization Servers tab exists, API AM isn’t enabled in your org. Contact your support team to enable this feature in your org or create a new developer edition org (opens new window).

Note your authorization server name and audience

This tutorial uses the default custom authorization server to secure your API. Make a note of its name and audience value to configure your API:

  1. From the API AM area in the Admin Console, select the Authorization Servers tab.
  2. Go to the entry for the default server and make a note of two values.
    • Audience: Found under audience. It should be api://default.
    • Authorization Server Name: Found under name. It should be default.

Moving on, where you see {yourAudience} and {yourAuthServerName} in this guide, replace them with your audience and authorization server name.

Note: You can either create a custom authorization server or use the default to protect your APIs. In either case, you need an appropriate licence to use them in production.

Create and configure a new web API to use Okta

Now that you have an authorization server and noted how to identify it, complete the following steps:

  1. Create an API project.
  2. Add the required packages to your project.
  3. Configure your API to use Okta.
  4. Create two endpoints to secure.

Create an API project

Add the required packages to your project

Configure your API to use Okta

Earlier you noted your authorization server name and audience. Add these and your Okta domain to your API's configuration.

Create two endpoints to secure

Create two endpoints in your project 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 different levels of access for different endpoints

In many APIs, all endpoints require authorization. There may be a mix of protected and unprotected endpoints in others. These examples show you how to assign protected and unprotected access to an endpoint.

Require authorization for all endpoints

Allow anonymous access for specific routes

Configure access on a per-route basis to allow a mix of protected and anonymous endpoints.

Enable CORS for your API

Enable Cross-Origin Resource Sharing (CORS) (opens new window) only if the API is being called from an app or API hosted on a different domain. For example, if your API is hosted on api.example.com while your app is accessing it from example.com, you must enable CORS.

Test that your API is secure

You can now test if your endpoint security works as intended. To do this, complete the following steps:

  1. Create an API services integration to represent another machine or service attempting to make requests to the API.
  2. Create a custom scope for the authorization server to assign to the API integration.
  3. Run the API.
  4. Use Postman (opens new window) to
    1. Request an access token for the API.
    2. Query both the \hello and \whoami endpoints.

Create an API Services integration

When another machine or service (rather than users) consumes an API, it uses the Client Credentials flow (opens new window) to identify itself and request an access token. Create an API services integration that has this flow enabled.

  1. Open the Admin Console for your org.
  2. Go to Applications > Applications to view the current app integrations.
  3. Click Create App Integration.
  4. Select API Services as the Sign-in method, and click Next.
  5. Enter an integration name, and click Save.

The configuration page for the new API services integration appears. Make a note of two values that you use to request your access token:

  • Client ID: Found on the General tab in the Client Credentials section.
  • Client Secret: Found on the General tab in the Client Credentials section.

Moving on, where you see {yourClientId} and {yourClientSecret} in this guide, replace them with your client ID and client secret.

Create a custom scope for the API

Scope is a way to limit an app's access to your API. An access token must include a list of the scopes an app integration can perform. Create a custom scope to query both endpoints for the API.

  1. Go to Security > API to view the API AM area.
  2. Select the Authorization Servers tab.
  3. Go to the entry for the default server and click its name.
  4. Select the Scopes tab and click Add Scope.
  5. Enter a name for the scope. For example, "AccessAll".
  6. Click Create.
  7. Ensure that the table contains the new scope.

Run Your API

Now, start your server to get your API running.

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

Test with Postman

Start Postman if it's not open already. First, you request an access token from Okta and then check your APIs are protected correctly.

Request an access token for the API

Make an HTTP POST request to /token (opens new window) using the client ID and secret you noted earlier.

  1. Select + in the Postman workbench to open a new request tab.

  2. Select GET and change it to POST.

  3. Enter https://{yourOktaDomain}/oauth2/{yourAuthServerName}/v1/token for the URL.

  4. In the Params tab, create two key-value pairs:

    1. Key: grant_type, Value: client_credentials
    2. Key: scope, Value: {yourCustomScope}
  5. Select the Authorization tab, and then select Basic Auth for type.

  6. Enter {yourClientId} for Username and {yourClientSecret} for Password.

  7. Select the Headers tab and add two new headers:

    1. Name: Cache-Control, Value: no-cache
    2. Name: Content-Type, Value: application/x-www-form-urlencoded
  8. Click Send to receive an access token.

    A screenshot of Postman making a call to /token and receiving an access token

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

Query the hello and whoami endpoints

Now you can test your secured API endpoints. First, test the \whoami endpoint, which requires authorization:

  1. Select + in the Postman workbench to open a new request tab.
  2. Enter
    for URL.
  3. Select the Authorization tab, and then select Bearer Token for type.
  4. Enter the token you received earlier for Token.
  5. Click Send.
  6. Ensure that you received a 200 OK response.
  7. Select the Authorization tab, and then select No Auth for type.
  8. Ensure that you received a 401 Unauthorized response.

Now test the hello endpoint which doesn't require authorization:

  1. Select + in the Postman workbench to open a new request tab.
  2. Enter
    for URL.
  3. Select the Authorization tab, and then select Bearer Token for type.
  4. Enter the token you received earlier for Token.
  5. Click Send.
  6. Ensure that you received a 200 OK response.
  7. Select the Authorization tab, and then select No Auth for type.
  8. Ensure that you still receive a 200 OK response.

Next steps

Learn more about concepts introduced in this guide: