Edit Page

Overview

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.

Postman and an Okta Collection

To use these collections, you’ll need to set up your local environment and import the collections. Then, you can send a test request and verify the results.

Sign Up for Okta

You’ll need a free Okta developer organization to get started. If you don’t have one already, sign up to create one.

When you create a new Okta organization, it will be assigned a base URL like dev-12345.oktapreview.com. This is your unique subdomain in Okta. oktapreview.com orgs are production-ready and can be used for development work or full-fledged apps, but they don’t include SLAs.

If you need organizations with guaranteed SLAs or enterprise features, let us know. These orgs use a different domain, like your-org.okta.com. Regardless of the domain or base URL style, you can use the following instructions to send requests to the Okta API.

Set Up Your Environment

  1. Create an API token for your org.
  2. Install the Postman app.
  3. Launch Postman and click the Import button. Select Import From Link, and paste this link into the textbox: https://developer.okta.com/docs/api/postman/example.oktapreview.com.environment Importing the Okta Example Environment

  4. Once it’s imported, make sure the example.oktapreview.com environment is selected. Postman app with collections

  5. Click the eye icon next to example.oktapreview.com and select Edit to replace or add these values:
    • Rename your environment to something you’ll recognize. For example, My Org.
    • url: Replace the example value with your org’s full URL. For example, https://dev-{id}.oktapreview.com. (Make sure you don’t include -admin in the subdomain!)
    • apikey: Enter the API token you created earlier, for example 00LzMWxMq_0sdErHy9Jf1sijEGexYZlsdGr9a4QjkS.
  6. Click Update to save your changes.

Import a Collection

Import the collection for the Users API:

Run in Postman

If you have Postman installed, clicking the button above gives you the option of importing the collection into Postman.

You can also import the collection by following the Web View link and downloading the collection as a JSON file. Import that file into Postman by clicking the Import button and browsing to your download location.

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 use the Collections Quick Reference. This tutorial only requires the Users API collection.

Send a Request

Once 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 the users in your org:

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

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.

Once you have completed this simple request, you’re ready to explore the Okta API!

Collections Quick Reference

Import any Okta API collection for Postman from the following list:

Collections Click to Run
Authentication Run in Postman
API Access Management (OAuth 2.0) Run in Postman
OpenID Connect Run in Postman
Client Registration Early Access Run in Postman
Sessions Run in Postman
Apps Run in Postman
Events Run in Postman
Factors Run in Postman
Groups Run in Postman
Identity Providers (IdP) Run in Postman
Logs Run in Postman
Admin Roles Run in Postman
Schemas Run in Postman
Users Run in Postman
Custom SMS Templates Run in Postman

These buttons are also available at the top of each API reference page in developer.okta.com.

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}}. Replace URL and body variables with the IDs of the resources you wish to specify.

To find an ID:

  1. List a resource collection with a search or filter. For example, list the users in your org, as you did in the previous section. List Users Response

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

Retaining the headers is helpful when you click HAL links in responses.

To retain the headers:

  1. Launch Postman and click the wrench icon.
  2. Select Settings.
  3. In the Headers column, enable Retain headers when clicking on links.