CyberArk Identity APIs

This topic describes how to get started with testing our APIs directly from the reference documentation.

Collect tenant specific information

To send requests to APIs in your CyberArk Identity tenant using the reference documentation, you will need the following tenant information, after which you can configure your tenant to allow requests from api-docs.cyberark.com.

Information	Description
tenant ID	A unique identifier for your tenant. This is a required request parameter for many APIs. To find your tenant ID, click the username icon, then select About.
tenant URL	The URL for your CyberArk Identity tenant. The tenant URL is either `.my.idaptive.app` or `.cyberark.cloud`. The tenant URL is a required parameter for all endpoints to send requests to your tenant. When you enter the tenant URL in the parameter field, `https://` is not required.

Enable the Send API Request functionality for your tenant

You can now test requests to endpoints from the Identity API reference documentation and view responses specific to your CyberArk Identity tenant.

In the CyberArk Identity Admin Portal, go to Settings > Authentication > Security Settings.
Add api-docs.cyberark.com to the list of trusted DNS domains for API calls. Specify trusted domains for API calls to prevent cross-origin resource sharing attacks before making the API calls from the Identity developer portal.
Note: This example adds the domain for this documentation site as a trusted domain. You can add any domain that you plan to send requests from.
In the API reference docs, select an endpoint from the table of contents.
Enter the required parameters, then select a language, and click Send API Request.

The Response section displays the response based on the tenant's request.

Export an API collection

Go to the API category that you want to export. For example, User Management.
In the top-right corner, click the Export drop-down menu, then select Bundled References.
The exported YAML file is automatically saved to your local drive.
Open an API client that supports importing collections as an OpenAPI Spec (OAS), then import the exported YAML file into your API client.

Note: OAS schemas imported into an API client are intended only as examples of API usage. CyberArk does not endorse, instruct, or support the use of any specific third-party API client. If you choose to use a third-party API client, you acknowledge that it is third-party software, subject to its own terms and conditions, and you do so at your own risk and liability. CyberArk disclaims any responsibility for damages, security issues, failures, or losses arising from or related to the use of any third-party software or services not provided by CyberArk.

Authentication quick start

For your application to use the CyberArk Identity Platform APIs, it must first authenticate the user. Your application uses these two endpoints in the authentication workflow:

Endpoint Description

/Security/StartAuthentication This endpoint initiates the authentication process for a user for a given tenant. Once invoked, the server receives the user's request to authenticate. If the user is registered, the server returns an array of security challenges to the client, each containing an array of factors, known as mechanisms, that the user must fulfill for each challenge. The user’s responses to these mechanisms are processed through the /Security/AdvanceAuthentication endpoint.

/Security/AdvanceAuthentication This endpoint sends the user’s responses to the mechanisms back to the server. If the server accepts these challenges, it returns an authentication token cookie to the client. Once the client receives the authentication token, it can use it to invoke subsequent endpoints on behalf of the user.

Endpoint	Description
/Security/StartAuthentication	This endpoint initiates the authentication process for a user for a given tenant. Once invoked, the server receives the user's request to authenticate. If the user is registered, the server returns an array of security challenges to the client, each containing an array of factors, known as mechanisms, that the user must fulfill for each challenge. The user’s responses to these mechanisms are processed through the `/Security/AdvanceAuthentication` endpoint.
/Security/AdvanceAuthentication	This endpoint sends the user’s responses to the mechanisms back to the server. If the server accepts these challenges, it returns an authentication token cookie to the client. Once the client receives the authentication token, it can use it to invoke subsequent endpoints on behalf of the user.

Note: After successfully invoking /Security/StartAuthentication, you must complete the authentication process with /Security/AdvanceAuthentication within five minutes.

You can enable external users (such as customers or temporary contractors) to use their existing social media credentials to log in to the CyberArk Identity user portal. For more information, see Enable social login.

At the end of a session, invoke the /security/logout endpoint to log the user out, passing the authentication token, acquired from the /Security/AdvanceAuthentication endpoint, in the header.

Important terms

Term	Description
Mechanism	A security factor that the user needs to fulfill as part of a challenge in the authentication process. This could include providing the correct password or entering the correct SMS response.
Challenge	An array of up to two challenges corresponding to the authentication profiles configured in the policy section of the admin portal. Each challenge contains an array of mechanisms.
Multi Factor Authentication	Authentication that requires the user to fulfill mechanisms from two challenges.
Out-of-Bounds Authentication	A mechanism involving a third-party entity, such as a smartphone, where the user needs to provide the correct SMS response.
Client	The application that invokes CyberArk Identity endpoints on behalf of a user.
Identity Provider (IdP)	An online service that provides user authentication on behalf of another online service. For example, a client redirects a user to log in on a social media website, which then returns the authentication result to the client.