REST API (OAuth 2.0) Credentials

Our upcoming APIs authenticate and authorize requests through OAuth 2.0 credentials.

Use a static REST API token to authorize requests for our existing API endpoints.
Learn more.

Quick Start

Get started with our latest APIs by performing the following steps:

  1. Create an API client for the desired application. Authorize this client by only assigning it the scope(s) required by the endpoint(s) with which it will interact.
  2. Use this client's ID and secret key to generate a temporary access token.

    Learn more.

  3. Authorize your API requests using the temporary access token generated in the previous step.

    Learn more.

Tenants

A tenant identifies your company or organization. Customers are assigned a single tenant. This tenant contains all of your REST API (OAuth 2.0) client credentials.

REST API (OAuth 2.0) Clients

You may add REST API (OAuth 2.0) client(s) to your tenant. Use an API client to generate credentials through which you may authorize your application to interact with one or more service(s).

A security best practice is to generate separate API clients for each unique application that will interact with our REST API service.

Use the following elements from your API client to generate credentials:

Learn more about generating an access token.

Scopes

A scope authorizes an API client to perform specific actions (e.g., create and retrieve configurations). A scope is defined using the following hierarchy:

Namespace.Service[.Type[:Modifier]]

The above hierarchy allows you to grant broad or narrow permissions to your client. Each element in this hierarchy is described below.

Key information:

Administering API Clients

You can create, modify, and delete API clients.

The recommended approach for switching to a new secret key is to create a secret key, update your API client to use the new secret key, and then delete the old secret key.

To create an account for an API client

  1. Navigate to the Identity dashboard.
  2. Click Clients from the side navigation pane.
  3. Verify that the Assigned to Tenant option is set to your customer account.
  4. Click Create New Client.
  5. In the Name option, assign a name that describes this API client.
  6. In the Permissions section, mark each scope that will be assigned to the API client.

    A security best practice is to only grant the set of scope(s) required for the automation task(s) that the client will perform.

  7. Click Create.

A Quick Start page is shown upon creating an account for your API client. This page contains a sample curl request and response for an access token. It also provides a sample curl request to our REST API service.

To modify an API client's account

  1. Navigate to the Identity dashboard.
  2. Click Clients from the side navigation pane.
  3. Verify that the Assigned to Tenant option is set to your customer account.
  4. Click on corresponding to the desired account.
  5. Perform one or more of the following tasks:

    • Update Name/Description

      1. Click the Settings tab.
      2. In the Name option, modify the account's name.
      3. In the Description option, describe the account's purpose.
      4. Click Save.
    • Update Access Token Duration

      1. Click the Settings tab.
      2. In the JWT Expiration in Seconds option, determine the number of seconds that an access token will remain valid after being issued.
      3. Click Save.
    • View Your Client ID

      1. Click the Settings tab.
      2. Find the Client ID option.
    • Add a Secret Key

      1. Click the Client Secrets tab.
      2. Click New Secret Key.
      3. In the Name option, assign a name to the new secret key.
      4. Click Create.
    • View or Copy a Secret Key

      1. Click the Client Secrets tab.
      2. Identify the secret key that you would like to view or copy.
      3. Click either of the following icons:

        • : Displays the secret key.
        • : Copies the secret key.
    • Delete a Secret Key

      The recommended approach for switching to a new secret key is to create a secret key, update your API client to use the new secret key, and then delete the old secret key.

      1. Click the Client Secrets tab.
      2. Identify the secret key that you would like to delete. Verify that it is no longer being used by your API client or script.
      3. Click next to the secret key identified in the previous step.
      4. Click I understand, please delete the client secret to confirm the deletion of the secret key.
    • Update Scopes

      1. Click the APIs tab.
      2. Mark each scope that will be granted to the client.
      3. Clear each scope that will be revoked from the client.
      4. Click Save.

To delete an API client's account

Verify that an API client is no longer in use prior to deletion. Account deletion cannot be undone.

  1. Navigate to the Identity dashboard.
  2. Click Clients from the side navigation pane.
  3. Verify that the Assigned to Tenant option is set to your customer account.
  4. Click on the desired account.
  5. Click the Settings tab.
  6. Click Delete Client.
  7. Click I understand, please delete the client to confirm the deletion of the API client.