API Authentication for CyberArk Identity Security Platform Shared Services

This topic describes the REST APIs used to authenticate to the CyberArk Identity Security Platform Shared Services and how to use them in your service'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 CyberArk Identity 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.

Secrets Hub

https://<sub domain>.secretshub.cyberark.cloud/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 your service role that enables them to send requests to the your service 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

    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 your service APIs.

Send requests to your service APIs

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