API Authentication for CyberArk Identity Security Platform Shared Services

This topic describes the REST APIs used to authenticate to CyberArk Identity Security Platform Shared Services and how to use them in Privilege Cloud's REST APIs for automating tasks.

Overview

Most REST API requests require an authentication token.

In CyberArk Identity Security Platform Shared Services, API authentication is defined through Identity Administration where you define the following for non-interactive API:

  • A dedicated API Service user, for non-interactive API. It is recommended to have a separate dedicated user for API activities based on the Service user . This user is dedicated to API and automation tasks, has least privilege access permissions, is not assigned MFA policies, and cannot access the Identity Administration User Portal.

  • Authentication method, for non-interactive API.Currently, grant_type=client_credentials is supported for non-interactive API.
    For interactive API, refer to Identity Administration API documentation.

CyberArk recommends to secure credentials in a centrally stored, logged and managed solution, such as CyberArkSecrets Manager

URL to be used

Usage

URL

Authentication - OAuth example
  • For current day systems, use the following URL:

    https://<identity-tenant-id>.id.cyberark.cloud/oauth2/platformtoken

    where <identity-tenant-id> is taken from the Identity Administration User Portal, as in the following example:

  • For 1st generation systems, continue using the following URL:

    https://<Identity-tenant-id>.my.idaptive.app/oauth2/platformtoken

    where <idaptive_id> is taken from the Identity Administration User Portal.

Use the resulting access token as Authorization bearer token.

Privilege Cloud API

https://<subdomain>.privilegecloud.cyberark.cloud/PasswordVault/API

Step 1: Create a Service user for API requests

In the Identity Administration Portal, create a service user that is an OAuth confidential client.

  1. Go to Core Services > Users , then click Add User and complete the following fields:

    • Login name

    • Display name

    • Password

  2. In the Status checklist, select the Is OAuth confidential client checkbox.

    The following checkboxes are selected by default: 

    • Is Service User

    • Password never expires

  3. Click Create User.

  4. Assign the newly created Service user(s) to the Privilege Cloud role that enables them to send requests to the Privilege Cloud APIs.

    Go to Core Services > Roles, then access the relevant role and add the Service user(s) as a member.

Service users are not displayed in the list of active users as they do not access the Identity Administration User Portal. To view service users, click All Users or All Service Users.

Step 2: Generate the authentication token using OAuth

  1. Run the request for the platform access token.

    URL

     
    https://<identity-tenant-id>.id.cyberark.cloud/oauth2/platformtoken

    Headers

    HTTP method

    POST

    Content type

    application/x-www-form-urlencoded

    Body parameters

    grant_type

    client_credentials

    client_id

    User name. The user login name as displayed in the Identity Administration portal Users list: login_name@<suffix>

    client_secret

    Password. The access password defined for the user

    Response

    The API response provides the requested token:

    access_token

    String representing the requested bearer token. Learn about access tokens.

    token_type

    Bearer.

    expires_in

    The validity period for the received token.

    The default validity period is 5 hours. The admin can set the access token lifetime on the OIDC custom app, described in how to set the access token lifetime.

  2. Store the bearer token received in the response access_token field and include it in the authorization header of requests to Privilege Cloud APIs.

Send requests to Privilege Cloud APIs

Use the token you created in the previous step as Authorization bearer token when sending requests to Privilege Cloud APIs.

For example:

Privilege Cloud API

https://<subdomain>.privilegecloud.cyberark.cloud/PasswordVault/<API>

Connector Management API

https://{tenant-subdomain}.connectormanagement.cyberark.cloud/api