Authenticating with Platform APIs

To authenticate with Platform APIs, perform the tasks mentioned below.

Creating a Role with the Desired Permissions

A local role is a key construct in the Delinea Platform. It is used in conjunction with groups to assign permissions to Users. Service users have no permissions except those explicitly granted.

Create a role with the permissions to access your desired protected resources. For example, if you wanted to access Identity resources, you would add the permission delinea.platform/identity/admin/read. For a list of permissions, please refer to the documentation.

To create a role and assign it permissions

  1. Log in to your tenant instance of Delinea Platform; that is, the URL https://{your-hostname}.delinea.app. For example, https://example.delinea.app.

  2. Select Access > Roles.

  3. Click Add Role.

  4. Fill out the following fields:

    • Role Type: Add New Custom Role

    • Role Name: Provide a name for the role; for example, API Service User Role

    • Role Description: Provide a human-readable description; for example, Role for service user accounts to access desired protected resources

  5. Click the Permissions tab and then click Add Permissions.

  6. Select one or more desired permissions.

  7. Click Assign.

Creating a Group with the Desired Role

Groups are used to assign permissions and roles to multiple users at once, simplifying the management of user access and privileges. For more detailed information, refer to the documentation.

To create a group and assign it roles

  1. Navigate to tenant instance of Platform (for example,. https://{your-hostname}.delinea.app or https://example.delinea.app ).

  2. Go to Access > Groups, and click Add Group.

  3. Enter the following:

    • Name: Provide a name for the Group. For example: API Access Group

    • Description: Describe the Group. For example: Group for Service User accounts to access protected platform resources.

      Click Save to continue.

  4. Click the group that you just created, and click the Roles tab and then click Assign Roles.

  5. Select the desired role, and click Assign.

Creating a Service User

Service users are specifically designed for non-interactive, programmatic access to the platform. They are intended for scenarios such as API integrations and automation scripts. Service users are not associated with regular users and they are intentionally excluded from the predefined Everybody user group.

To create a service user, follow the detailed steps outlined in Adding Users. The guide provides comprehensive instructions on configuring service users, and assigning appropriate permissions.

Retrieving an Access Token Using the client_credentials Grant Type

For the next steps, we offer a Postman collection to help you get started.

The OAuth 2.0 client credentials grant flow [ref: oauth.com] allows a web service (i.e. confidential client) to use its own credentials, instead of impersonating a user to authenticate when calling another web service (For example: Delinea Platform). The grant type is specified in RFC 6749 and can be used to access web-hosted resources by using the identity of an application.

This grant type is commonly used for server-to-server interactions that must run in the background, without immediate interaction with a user and is often referred to as daemons or service accounts.

To retrieve an access token via cURL

  1. Use the following cURL command to retrieve the Access + Refresh Token:

    Copy 
    curl 'https://{your-hostname}.delinea.app/identity/api/oauth2/token/xpmplatform' \ 
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'scope=xpmheadless' \
    --data-urlencode 'client_id={clientIdValue}' \
    --data-urlencode 'client_secret={clientSecretValue}'

  2. Replace the following variables with values from the earlier procedures.

    1. {tenantHostname} - Tenant Hostname

    2. {clientIdValue} - The username from Creating a Service User.

    3. {clientSecretValue} - The password from Creating a Service User.

    You will end up with a cURL request like the one below:

    Copy 
    curl 'https://{your-hostname}.delinea.app/identity/api/oauth2/token/xpmplatform' \ 
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'scope=xpmheadless' \
    --data-urlencode 'client_id=test.api.user@example' \
    --data-urlencode 'client_secret=yourVeryStrongSecret'

    If the request is successful, this resource returns an HTTP/2 200 Ok response, such as the one below.

    Copy 
    HTTP/2.0 200 Ok
    {
      "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjVmNGFkNDZmLTFlZjgtNDgwNC1iNWUyLTQ3YmYyZDA0NWRhNSIsImFwcF9pZCI6InhwbXBsYXRmb3JtIn0.ewogICJ1X2F1dGhtIjogIk9BdXRoMiIsCiAgInNlc3NfaWQiOiAiMmY4YTdhNGMtZGI2OC00NThlLWEwNjMtMTc0M2YwYjY3NDNlIiwKICAidGVuYW50X2lkIjogImMyNjdlZTY2LWM4YmItNDkzMy05Y2RhLTJhOTJiOTVhNzkwZCIsCiAgImlhdCI6IDE3MjQzNjY2MTAsCiAgImNsaWVudF9pZCI6ICIwMGUzZjJhMS1lMDlmLTQ2MGYtOGQ3Mi03M2U3ZmY4NGY5ZjEiLAogICJzdWIiOiAiMDBlM2YyYTEtZTA5Zi00NjBmLThkNzItNzNlN2ZmODRmOWYxIiwKICAidV9pZCI6ICIwMGUzZjJhMS1lMDlmLTQ2MGYtOGQ3Mi03M2U3ZmY4NGY5ZjEiLAogICJhdXRoX3RpbWUiOiAxNzI0MzY2NjEwLAogICJleHAiOiAxNzI0MzcwMTYwLAogICJzY29wZSI6ICJ4cG1oZWFkbGVzcyIsCiAgImF1ZCI6ICIwMGUzZjJhMS1lMDlmLTQ2MGYtOGQ3Mi03M2U3ZmY4NGY5ZjEiLAogICJ1X2Rpc3BuYW1lIjogIkFQSSBTZXJ2aWNlIEFjY291bnQgVXNlciIsCiAgInZlciI6ICIxLjAiLAogICJhbGciOiAiUlMyNTYiLAogICJhbXIiOiAiT0F1dGgyIiwKICAiaXNzIjogImh0dHBzOi8vdGVuYW50LmRlbGluZWEuYXBwL2lkZW50aXR5LyIsCiAgImFwcF9pZCI6ICJ4cG1wbGF0Zm9ybSIsCiAgInR5cCI6ICJKV1QiLAogICJuYW1lIjogImFwaS51c2VyQHRlbmFudC5jb20iLAogICJqdGkiOiAiMDAwMGI0NWItNDkxZC00OGI3LTg2NWMtMDYwNDEzYTRlNTg2IiwKICAiYWNyIjogewogICAgInByb2ZpbGVzIjoge30sCiAgICAibWVjaGFuaXNtcyI6IHt9CiAgfQp9.oSNImJKYHyWIEGgX56yFj3chI6yI-sYgbni7sbSRwQCQS-s53wYnOnUVXvaSTmGKaRggKIDcJ5FBxQJYJLyfBpiZACUFeJAVDXDPtbelo2CWzqe-VgtTPEHvMgNbd4Hd_JWZiavCZIwskD5nlEhRFoNaFELCQ6Ip8Gj95PqPEfwoqqDNEa0NK9HO0SjPzI7s54vzdUs7xZtseCBcnwl-8pyxe4rOml594YAIKxClW-P4VBwY5icTvCojyvROh6F6DXGzWeIVVPZnd6ZHkwnsonVADvzf4AIg9MzTF2E4hbgYQZeB6HuQhMblB1zwoYnRBlo9T0qWaZofjIS2uOSlww",
      "refresh_token": "3FEF5DBCFC798EE5E16BBDA2FB39F145D9D11241B2A6174A85C925203893C766",
      "token_type": "Bearer",
      "expires_in": 3582,
      "session_expires_in": 43200,
      "scope": "xpmheadless"}

    Below are explanations of the terms used in the response:

    • access_token - The requested access token. The app can use this token to authenticate to the protected resource, such as a specific Delinea Platform API (such as Identity).

    • token_type - Indicates the token type value. Delinea Platform supports the Bearer type.

    • expired_in - The amount of time that an access token is valid (in seconds).

      For the actual expiry time, you will have to decode the access_token - using a tool like (jwt.io) - and inspect the exp claim in the payload. The expiry time is in Unix time.

    • refresh_token - Used to exchange the access_token for a new one after it has expired.

    • session_expires_in - The time in seconds that the user’s session is valid. By default, a session is valid for 12 hours.

      During this time the refresh_token can be used to exchange an expired access_token for a new one.

  3. Take note of the access_token and refresh_token from the response.

    The access_token is required in order to access protected Delinea Platform resources:

    • You can use the following alternate cURL command to save the response to an Environment Variable:

      Copy 
      export ServiceUserXpmAccessTokenResponse=$(curl --verbose --location 'https://your-hostname.delinea.app/identity/api/oauth2/token/xpmplatform' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=client_credentials' --data-urlencode 'scope=xpmheadless' --data-urlencode 'client_id=test.api.user@example' --data-urlencode 'client_secret=yourVeryStrongSecret')
      echo $ServiceUserXpmAccessTokenResponse

    • You can use the following Bash/ZSH commands to extract the access_token and refresh_token:

      Copy 
      export ServiceUserAccessToken=$(echo $ServiceUserXpmAccessTokenResponse | jq --raw-output '.access_token')
      echo $ServiceUserXpmAccessToken

      export ServiceUserXpmRefreshToken=$(echo $ServiceUserXpmAccessTokenResponse | jq --raw-output '.refresh_token')
      echo $ServiceUserXpmRefreshToken

Exchanging a Refresh Token for a New Access Token

Access tokens are typically short-lived (for example, 1 hour). The Refresh Token grant type [ref: RFC 6749 - Section 1.5] is used by clients to exchange a refresh token for an access token when the access token has expired. This allows the client to continue to have a valid access token without further interaction with the user.

In the client credentials grant flow, the client is identical to the resource owner and requests an access token to their resources, not on behalf of a user.

The client credentials grant flow does not typically issue a refresh token. The client is assumed to be in the position of the credentials (client id & secret) and can request a new token for itself at any time without involving a separate resource owner, which it makes the refresh token unnecessary in this context.

One may argue that returning the access token is sufficient and reduces cognitive complexity for confidential clients.

You will need the access token and refresh token available to complete the following procedure. These steps assume that you have exported the access token and refresh token already into the two respective environment variables ServiceUserXpmAccessToken and ServiceUserRefreshToken.

To exchange a refresh token for an access token

  1. Use the following cURL command to exchange the Access + Refresh Token:

    Copy 
    curl 'https://{your-hostname}.delinea.app/identity/api/oauth2/token/xpmplatform' \ 
    --header "Authorization: Bearer {serviceUserAccessToken}"
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=refresh_token' \
    --data-urlencode 'refresh_token={serviceUserRefreshToken}

  2. Replace the following variables with values from the previous procedures:

    • {your-hostname} - Tenant Hostname

    • {serviceUserAccessToken} - The access_token from Retrieving an Access Token Using the client_credentials Grant Type.

    • {serviceUserRefreshToken} - The password from Retrieving an Access Token Using the client_credentials Grant Type.

      You'll now have a cURL request like the one below:

      Copy 
      curl 'https://{tenanthostname}.{environment}/identity/api/oauth2/token/xpmplatform' \ 
      --header "Authorization: Bearer $ServiceUserAccessToken"
      --header 'Content-Type: application/x-www-form-urlencoded' \
      --data-urlencode 'grant_type=refresh_token' \
      --data-urlencode "refresh_token=$ServiceUserXpmRefreshToken"

      If the request is successful, the resource returns an HTTP/2 200 Ok response, as outlined below:

      Copy 
      HTTP/2.0 200 Ok
      {
        "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjVmNGFkNDZmLTFlZjgtNDgwNC1iNWUyLTQ3YmYyZDA0NWRhNSIsImFwcF9pZCI6InhwbXBsYXRmb3JtIn0.ewogICJ1X2F1dGhtIjogIk9BdXRoMiIsCiAgInNlc3NfaWQiOiAiNGFiMTM5ZWQtZDc0MC00MjQzLWE2YWYtYWJhMjBkZDI5OGNjIiwKICAidGVuYW50X2lkIjogImMyNjdlZTY2LWM4YmItNDkzMy05Y2RhLTJhOTJiOTVhNzkwZCIsCiAgImlhdCI6IDE3MjQzNjY2MTAsCiAgImNsaWVudF9pZCI6ICIwMGUzZjJhMS1lMDlmLTQ2MGYtOGQ3Mi03M2U3ZmY4NGY5ZjEiLAogICJzdWIiOiAiMDBlM2YyYTEtZTA5Zi00NjBmLThkNzItNzNlN2ZmODRmOWYxIiwKICAidV9pZCI6ICIwMGUzZjJhMS1lMDlmLTQ2MGYtOGQ3Mi03M2U3ZmY4NGY5ZjEiLAogICJhdXRoX3RpbWUiOiAxNzI0MzY2NzkwLAogICJleHAiOiAxNzI0MzcwMzkwLAogICJzY29wZSI6ICJ4cG1oZWFkbGVzcyIsCiAgImF1ZCI6ICIwMGUzZjJhMS1lMDlmLTQ2MGYtOGQ3Mi03M2U3ZmY4NGY5ZjEiLAogICJ1X2Rpc3BuYW1lIjogIkFQSSBTZXJ2aWNlIEFjY291bnQgVXNlciIsCiAgInZlciI6ICIxLjAiLAogICJhbGciOiAiUlMyNTYiLAogICJhbXIiOiAiT0F1dGgyIiwKICAiaXNzIjogImh0dHBzOi8vdGVuYW50LmRlbGluZWEuYXBwL2lkZW50aXR5LyIsCiAgImFwcF9pZCI6ICJ4cG1wbGF0Zm9ybSIsCiAgInR5cCI6ICJKV1QiLAogICJuYW1lIjogImFwaS51c2VyQHRlbmFudC5jb20iLAogICJqdGkiOiAiMmI0ZGM4NzUtM2UwZi00MTBhLWE0NzQtNzcyN2FhNWYzYWM0IiwKICAiYWNyIjogewogICAgInByb2ZpbGVzIjoge30sCiAgICAibWVjaGFuaXNtcyI6IHt9CiAgfQp9.D4eXb2Hm9Sqdacwc-otq5ugcaM_Nwr4KkslIR-emySA9iR3zhqPQduQOdyKVe0xeNWmQi-bsodLzdlwzAWJ-X9Bb_MT60L9bYKgB6zhUDaHLAoiO7AzIQ_RmTbXxKC6UykzI6VBgSajADTewoqwDUZoss2vqON59CzwT9xawy1PtWIzz94FCl66SYE0bfx2neIkgPrkuq_UoI_qum-FOUBrgmlBeRc1nj1pL3Beva4W64vWFqAiHblzVVa-iac13z4QHyFeL7YF5V1FDS5vGlRCEbuRLJTSyEC1-oQ1105WUxXncO0qRx8XJvU1V0fbxq8Xtad6bKLYVjs8ytHpViA",
        "refresh_token": "4BE0A0CA95EF6425D5606881F946C25FBB2453AB2B8E8F45BA6BD4D0883F7033",
        "token_type": "Bearer",
        "expires_in": 3555,
        "session_expires_in": 42789,
        "scope": "xpmheadless"
      }

  3. Make sure to note down the access_token and refresh_token from the response.

    1. You can use the following alternate cURL command to save the response to an Environment Variable:

      Copy 
      export ServiceUserXpmAccessTokenResponse=$(curl 'https://{tenanthostname}.{environment}/identity/api/oauth2/token/xpmplatform' --header "Authorization: Bearer $ServiceUserAccessToken" --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=refresh_token' --data-urlencode "refresh_token=$ServiceUserXpmRefreshToken")
      echo $ServiceUserXpmAccessTokenResponse

    2. You can use the following Bash/ZSH commands to extract the access_token and refresh_token:

      Copy 
      export ServiceUserAccessToken=$(echo $ServiceUserXpmAccessTokenResponse | jq --raw-output '.access_token')
      echo $ServiceUserXpmAccessToken

      export ServiceUserXpmRefreshToken=$(echo $ServiceUserXpmAccessTokenResponse | jq --raw-output '.refresh_token')
      echo $ServiceUserXpmRefreshToken

 

Querying Delinea Platform Resources Using an Access Token

Please note, that you will need the access token available. The below steps assume that you have exported the access token to the Environment Variable ServiceUserXpmAccessToken.

The steps below apply to any Delinea Platform public API role. The example below accesses the protected Users resource in the Identity Public API.

To query protected Delinea Platform resources using an Access token via cURL

  1. Use the following cURL command to query Identity:

    Copy 
    curl 'https://{your-hostname}.delinea.pp/identity/api/entities/users/{userdisplayname}' \ 
    --header "Authorization: Bearer {serviceUserAccessToken}"

  2. Replace the following variables with values from step 1.a.i.:

    1. {tenantHostname} - Tenant Hostname (e.g. example)

    2. {serviceUserAccessToken} - The access_token from Retrieving an Access Token Using the client_credentials Grant Type.

    3. {userdisplayname} - The user's display name you would like to search for. (for example, username@example.com)

  3. You will end up with a cURL request like the one below:

    Copy 
    curl 'https://{your-hostname}.delinea.app/identity/api/entities/users/username@example' \
    --header "Authorization: Bearer $ServiceUserAccessToken" 

    • If the request is successful, the resource returns an HTTP/2 200 Ok response, as outlined below: