Test the Okta REST APIs using Postman

A great way to learn an API is to issue requests and inspect the responses. You can easily use our Postman collections to do just that. To use these collections, you need to set up your local environment and import a collection. You can then send a test request and verify the results.

Sign up for Okta

You need a free Okta developer edition org to get started. Don't have one? Create an org for free (opens new window). When you create a new Okta org, the org is assigned a base URL such as dev-1234.okta.com. This is your unique subdomain in Okta.

Set up your environment

1. Create an API token for your org.

   Note: Alternatively, you can create an OAuth 2.0 access token for use with a number of Okta endpoints. This is a feature that allows you to interact with Okta APIs using scoped OAuth 2.0 access tokens. Each access token enables the bearer to perform specific actions on specific Okta endpoints, with that ability controlled by which scopes the access token contains.

2. Install the Postman app (opens new window).

3. Start Postman if it's not open already.

4. In the upper-left corner, click Import.

5. In the Import dialog box, click Link and then paste the following link into the Enter a URL box: https://developer.okta.com/docs/api/postman/example.oktapreview.com.environment.

   Note: You can also download this environment locally and import it as a file.

6. Click Continue and then Import to confirm your environment import.

7. In the upper-right corner, click the box that lists the environments and then select ${yourOktaDomain} from the list. The initial value is No Environment if you just installed Postman.

8. In the upper-right corner, next to ${yourOktaDomain}, click Environment quick look .
9. In the upper-right corner of the ${yourOktaDomain} dialog box, click Edit.

10. In the Manage Environments dialog box, do the following:
    • In the Environment Name box, delete the placeholder text and name your environment, for example: John's Okta Org.
    • For the url variable, in the Initial Value and Current Value columns, replace the placeholder text with your org's full URL, for example: https://dev-1234567.okta.com. Remember to remove the -admin part of your subdomain.
    • For the apikey variable, in the Initial Value and Current Value columns, enter your API token that you created earlier, for example: 00LzMWxMq_0sdErHy9Jf1sijEGexYZlsdGr9a4QjkS.

11. Scroll to the bottom of the dialog box and click Update.
12. To close the dialog box, click the X in the upper-right corner.

Import a collection

Use the Run in Postman button below to import the Users API collection:

(opens new window)

You can then select the option to open the collection using the Postman app. Alternatively, you are also given the option to use the Web View link to download the collection as a JSON file and import it:

• Import that file into Postman by selecting Import from the File menu.
• In the Import window, leave Import File selected and click Choose Files.
• Browse to your download location, select the JSON file, and click Open.
• Click Import.

Note: You can import and work with the rest of the Okta API using the link at the top of each API reference page, or see all Postman collections. This tutorial only requires the Users API collection.

Send a request

After you've imported the Users API collection and added your Okta org information to your environment, you're ready to send a request.

To make sure everything works, send a request to list all of the users in your org:

1. Select the Collections tab in Postman and expand the Users (Okta API) collection.
2. Expand the List Users folder and select List Users. This loads the List Users request into Postman, ready to send.
3. Click Send. The result pane automatically displays the results of your request:

If you receive an error, it's likely that one of the values in the environment isn't set correctly. Check the values and try again.

After you have completed this simple request, you're ready to explore the Okta API.

Tips

Now that you have a working collection, you can use the following tips to work more efficiently.

Find IDs for Okta API requests

Your imported collections contain URLs and JSON request bodies that have sample data with variables such as ${userId}. You can replace URL and body variables with the IDs of the resources that you want to specify.

1. To get a user's ID, for example, send a request to list the users in your org like you did in the previous section. Each user listed in the response has an ID:

2. Copy the id of the resource, in this example the id for Tony Stark, for use in your next request.

Retain headers when you click links

You can retain headers when when you click HAL links in the responses.

To retain the headers:

1. Click the wrench icon from the toolbar in the upper-right corner of the page.
2. Select Settings.
3. In the HEADERS column, enable Retain headers when clicking on links.

Next steps

Now that you have imported a collection and successfully tested a request and received a response, you can use Postman to learn more about the Okta APIs.

Access an Okta API, download the collection for that API, and try the request examples that come with the collection to help you more fully understand how that API works.