Using Secret Server APIs from Delinea Platform

When working with the Delinea Platform, one of the key integrations you’ll often need to perform is retrieving an access token and using it to authenticate API calls to Secret Server. This guide will walk you through the necessary steps for generating an access token and calling the Secret Server API.

Requirements

Before you begin, make sure that you have the following:

Access to a Delinea Platform tenant
A Client Credentials - Platform service account credential (client ID and secret)
- Grant appropriate Secret Server permissions to the service account, according to the intended API access use cases.
Your Secret Server API Endpoint base URL (also called the Secret Server URL)

The format is usually like this: https://< your-secret-server-cloud-instance>/api/v2.

Get the Secret Server URL by one of the following ways:
- Navigate to your platform tenant and go to Settings > Secret Server Connection.
  The Secret Server URL is listed there.
- Use the Vault Broker API to retrieve the Secret Server URL.

Using the Vault Broker API to Retrieve the Secret Server URL

Here's an example of how you can use the vault broker API to retrieve the Secret Server URL:

Request example:

Copy

GET  https://<your-delinea-platform-tenant>/vaultbroker/api/vaults HTTP/1.1

Headers:
Authorization: Bearer your_access_token_value
Content-Type: application/json

Response example:

Copy

{
    "vaults": [
        {
            "vaultId": "*****",
            "name": "GlobalDefaultVault",
            "type": "SecretServerCloud",
            "isDefault": true,
            "isGlobalDefault": true,
            "isActive": true,
            "connection": {
                "url": "https://<your-secret-server-cloud-instance>/",
                "oAuthProfileId": "*****"
            }
        }
    ]
}

Generating an Access Token

The first step is to authenticate with Delinea Platform and retrieve an access token. You'll use the token in all subsequent API requests to authorize access to Secret Server.

You request the access token by sending an HTTP POST request to the Delinea Identity Authorization endpoint.

Example:

Copy

POST https://<your-delinea-platform-tenant>/identity/api/oauth2/token/xpmplatform HTTP/1.1

Headers:
Content-Type: application/x-www-form-urlencoded

Body:
grant_type=client_credentials
client_id=<your-client-id>
client_secret=<your-client-secret>
scope= xpmheadless

If the request is successful, you receive a JSON response containing the access token.

Example:

Copy


{
    "access_token": "your_access_token_value",
    "refresh_token": "your_refresh_token_value",
    "token_type": "Bearer",
    "expires_in": 3602,
    "session_expires_in": 43200,
    "scope": "xpmheadless"
}

Make sure to store the access token in a safe place; you'll need it to authenticate subsequent API requests.

Using the Access Token to Call the Secret Server API

Now that you have an access token, you can authenticate requests to the Secret Server API by including the token in the Authorization header.

For example, here's how you can use the access token to retrieve a secret by its ID.

Example request:

Copy

GET https://<your-secret-server-cloud-instance>/api/v2/secrets/{secretId}

Headers:
Authorization: Bearer your_access_token_value
Content-Type: application/json

If the access token is valid and the request is successful, you will receive a response containing the secret’s details.

Example response:

Copy

{
    "id": 1,
    "name": "Example account",
    "secretTemplateId": 9,
    "folderId": 13,
    "active": true,
    "items": [
        {
            "itemId": 1,
            "fileAttachmentId": null,
            "filename": null,
            "itemValue": "https://example.com/",
            "fieldId": 38,
            "fieldName": "URL",
            "slug": "url",
            "fieldDescription": "The online address where the information is being secured.",
            "isFile": false,
            "isNotes": false,
            "isPassword": false,
            "isList": false,
            "listType": "None"
        },
        {
            "itemId": 2,
            "fileAttachmentId": null,
            "filename": null,
            "itemValue": "user@example.com",
            "fieldId": 39,
            "fieldName": "Username",
            "slug": "username",
            "fieldDescription": "The name associated with the web password.",
            "isFile": false,
            "isNotes": false,
            "isPassword": false,
            "isList": false,
            "listType": "None"
        },
        {
            "itemId": 3,
            "fileAttachmentId": null,
            "filename": null,
            "itemValue": "examplePassword",
            "fieldId": 40,
            "fieldName": "Password",
            "slug": "password",
            "fieldDescription": "The password used to access the URL.",
            "isFile": false,
            "isNotes": false,
            "isPassword": true,
            "isList": false,
            "listType": "None"
        },
        {
            "itemId": 4,
            "fileAttachmentId": null,
            "filename": null,
            "itemValue": "",
            "fieldId": 41,
            "fieldName": "Notes",
            "slug": "notes",
            "fieldDescription": "Any comments or additional information for the secret.",
            "isFile": false,
            "isNotes": true,
            "isPassword": false,
            "isList": false,
            "listType": "None"
        }
    ],
    "launcherConnectAsSecretId": -1,
    "checkOutMinutesRemaining": 0,
    "checkedOut": false,
    "checkOutUserDisplayName": "",
    "checkOutUserId": -1,
    "isRestricted": false,
    "isOutOfSync": false,
    "outOfSyncReason": "",
    "autoChangeEnabled": false,
    "autoChangeNextPassword": null,
    "requiresApprovalForAccess": false,
    "requiresComment": false,
    "checkOutEnabled": false,
    "checkOutIntervalMinutes": -1,
    "checkOutChangePasswordEnabled": false,
    "accessRequestWorkflowMapId": -1,
    "proxyEnabled": false,
    "sessionRecordingEnabled": false,
    "restrictSshCommands": false,
    "jumpboxRouteId": null,
    "allowOwnersUnrestrictedSshCommands": false,
    "isDoubleLock": false,
    "doubleLockId": -1,
    "enableInheritPermissions": false,
    "passwordTypeWebScriptId": -1,
    "siteId": 1,
    "enableInheritSecretPolicy": true,
    "secretPolicyId": -1,
    "lastHeartBeatStatus": "Pending",
    "lastHeartBeatCheck": null,
    "failedPasswordChangeAttempts": 0,
    "lastPasswordChangeAttempt": null,
    "secretTemplateName": "Web Password",
    "responseCodes": [],
    "webLauncherRequiresIncognitoMode": false
}

About Token Expiration

The access token is valid for a specific period up to 3600 seconds. After it expires, you will need to request a new token. It’s a good practice to refresh the token programmatically before it expires, depending on your application’s workflow.

You can keep track of the expires_in field from the token response and refresh the token when necessary.

Error Handling

If the access token is missing, invalid, or expired, the API will return an `Unauthorized` error. Here’s an example of the error you might receive:

Copy


{
    "message": "Authentication failed or expired token."
}

In this case, you need to request a new access token and retry the API call.