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.
Get started with our latest APIs by performing the following steps:
Use this client's ID and secret key to generate a temporary access token.
Authorize your API requests using the temporary access token generated in the previous step.
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.
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:
Secret Key: A client must pass this private key for identity verification when requesting an access token. View a client's secret key(s) from the client's Client Secrets tab.
If you suspect that a secret key has been compromised, then you should immediately create a new secret key, update your client to use the new secret key, and then delete the old secret key.
Learn more about generating an access token.
A scope authorizes an API client to perform specific actions (e.g., create and retrieve configurations). A scope is defined using the following hierarchy:
The above hierarchy allows you to grant broad or narrow permissions to your client. Each element in this hierarchy is described below.
Namespace: Identifies a broad category (i.e., ).
Service: Identifies a product or a category of products (e.g., , , and ).
A scope may identify a product or a category of products through multiple services.
Example:
Both and identify services in the following scope: ).
Type: Optional. Identifies a feature or a type of permission.
Example:
In the following scope,
identifies a type of permission. In this case, grants permissions to retrieve, submit, and delete deploy requests.Modifier: Optional. Restricts the scope to a subset of permissions. Valid values are:
Example:
The
modifier in the following scope authorizes the retrieval of deploy requests:Key information:
A broad scope grants all of the scopes underneath it.
Example:
The following scope authorizes full access to Rules Engine:
Alternatively, the following scope authorizes the creation, retrieval, modification, and deletion of Rules Engine drafts and policies:
One or more scope(s) must also be defined when requesting an access token. You may only specify a scope that has been explicitly granted or inherited from a broader scope.
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
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.
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
Perform one or more of the following tasks:
Update Name/Description
Update Access Token Duration
View Your Client ID
Add a Secret Key
View or Copy a Secret Key
Click either of the following icons:
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.
Update Scopes
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.