# Getting Started with SailPoint APIs

# Admin Access

To use SailPoint APIs, you must have admin access to an Identity Now tenant, or be able to request API credentials from your tenant's admin.

# Finding your Org/Tenant Name

You will need to know your org/tenant name in order to form the proper URL for an API request. You can find your org/tenant name by logging into IdentityNow, navigating to the Admin UI, and clicking on the Dashboard dropdown and selecting the Overview page. The org name is displayed within the Org Details section of the dashboard.

# Making Your First API Call

To get started, you will need an API client to generate access tokens that can be used to authenticate requests:

  • As an admin, browse to your API Management Admin Page at https://{tenant}.identitynow.com/ui/admin/#admin:global:security:apimanagementpanel and create an API client with the Client Credentials grant type. If you are not an admin of your tenant, you can ask an admin to create this for you.

  • Save the Client Secret somewhere safe, as you won't be able to view or change it later.

  • To create an access token, use the following cURL command, replacing {tenant} with your IdentityNow tenant:

    curl --location --request POST 'https://{tenant}.api.identitynow.com/oauth/token?grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}'
    
  • The response body will contain an access_token, which will look like a long string of random characters.

  • To test your token, execute the following cURL command, replacing {tenant} with your IdentityNow tenant and access_token with your new access token:

    curl --request GET --url 'https://{tenant}.api.identitynow.com/v3/public-identities?limit=1' --header 'authorization: Bearer {access_token}'
    
  • If successful, you should get a JSON representation of an identity in your tenant.

For more information about SailPoint Platform authentication, see API Authentication

# Rate Limits

There is a rate limit of 100 requests per access_token per 10 seconds for V3 API calls through the API gateway. If you exceed the rate limit, expect the following response from the API.

HTTP Status Code: 429 Too Many Requests

Headers:

  • Retry-After: {seconds to wait before rate limit resets}

# Authorization

Each API resource requires a specific level of authorization attached to your access_token. Please review the authorization constraints for each API endpoint. Tokens generated outside of a user context, like the Client Credentials we generated above to make your first API call, will be limited in the endpoints that it can call. If your token doesn't have permission to call an endpoint, you will receive the following response:

HTTP Status Code: 403 Forbidden

Response Body:

{
    "detailCode": "403 Forbidden",
    "trackingId": "fca9eb2227514d6d90cd4a1d1cdc255c",
    "messages": [
        {
            "locale": "en-US",
            "localeOrigin": "DEFAULT",
            "text": "The server understood the request but refuses to authorize it."
        }
    ]
}

# Using an API Tool

There are several API tools that make exploring and testing APIs easier than using the command line or a programming language. One such tool is Postman (opens new window). To import the SailPoint REST APIs into a tool like Postman, you must first download the REST specification. Navigate to https://developer.sailpoint.com/apis/v3 (opens new window) and click the "Download OpenAPI specification" button. You can then import the JSON file in Postman by using the import wizard (opens new window) within Postman.