BeyondTrust Secrets API Documentation

The BeyondTrust Secrets API provides secure, programmatic access to secrets, folders, and integrations. It supports secret versioning, tagging, folder management, and integration with external systems.

API Version: 2026-04-28
Base URL: https://api.beyondtrust.io/site/<site-id>/secrets

Getting Started

Authentication

The API uses JWT Bearer Token or Personal Access Tokens (PATs) authentication. Include your access token in the Authorization header for all requests:

Authorization: Bearer <your-jwt-token>

or

Authorization: Bearer <your-pat-token>

API Versioning

All requests must include the API version header:

bt-secrets-api-version: 2026-04-28

Example Request

curl -X GET "https://api.beyondtrust.io/site/<site-id>/secrets/static/my-secret?folder=prod/db" \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "bt-secrets-api-version: 2026-04-28"

API Reference

Session

Check Authentication Session

Verify if the current authentication session is valid.

GET /session

Response (200):

{
  "valid": true
}

Static Secrets

List Secrets

Retrieve a list of secrets, optionally filtered by path, version, or deletion status.

GET /static

Query Parameters:

Response (200):

{
  "data": [
    {
      "path": "/prod/db/password",
      "type": "static",
      "metadata": {
        "id": "b7e6f8a1-9c2d-4e3a-8b7a-2d6e4f1c9a2b",
        "tags": { "env": "prod", "owner": "db" },
        "version": 3,
        "createdAt": "2025-09-12T14:00:00-06:00"
      },
      "versions": [
        { "version": 3, "createdAt": "2025-09-12T14:00:00-06:00" },
        { "version": 2, "createdAt": "2025-09-10T14:00:00-06:00" }
      ]
    }
  ]
}

Get Secret by Path

Retrieve a specific secret by its path.

GET /static/{name}

Path Parameters:

Query Parameters:

Response (200):

{
  "path": "/prod/db/password",
  "secret": {
    "password": "supersecret"
  },
  "metadata": {
    "id": "b7e6f8a1-9c2d-4e3a-8b7a-2d6e4f1c9a2b",
    "tags": { "env": "prod", "owner": "db" },
    "version": 3,
    "createdAt": "2025-09-12T14:00:00-06:00"
  },
  "versions": [
    { "version": 3, "createdAt": "2025-09-12T14:00:00-06:00" },
    { "version": 2, "createdAt": "2025-09-10T14:00:00-06:00" }
  ]
}

Create Secret

Create a new secret at the specified path.

POST /static/{name}

Path Parameters:

Query Parameters:

Request Body:

{
  "secret": {
    "password": "supersecret",
    "username": "admin"
  }
}

Response (201):

{
  "path": "/prod/db/password",
  "secret": {
    "password": "supersecret"
  },
  "metadata": {
    "id": "b7e6f8a1-9c2d-4e3a-8b7a-2d6e4f1c9a2b",
    "tags": {},
    "version": 1,
    "createdAt": "2025-09-14T14:00:00-06:00"
  }
}

Update Secret

Update the value or metadata of an existing secret using JSON Merge Patch (RFC 7396).

PATCH /static/{name}

Path Parameters:

Query Parameters:

Request Body:

{
  "secret": {
    "password": "newsecret"
  }
}

Note: This endpoint uses JSON Merge Patch semantics:

• Fields present in the request will be updated with the provided values
• Fields set to null will be deleted from the secret
• Fields not present in the request remain unchanged

Response: 204 No Content

Delete Secret

Delete a secret at the specified path.

DELETE /static/{name}

Path Parameters:

Query Parameters:

Response: 204 No Content

Restore Secret

Restore a previously deleted secret.

POST /static/{name}/restore

Path Parameters:

Query Parameters:

Response (200): Returns the restored secret object.

Get Secret Metadata

Retrieve metadata for a specific secret.

GET /static/{name}/metadata

Path Parameters:

Query Parameters:

Response (200):

{
  "id": "b7e6f8a1-9c2d-4e3a-8b7a-2d6e4f1c9a2b",
  "tags": { "env": "prod", "owner": "db" },
  "version": 3,
  "createdAt": "2025-09-12T14:00:00-06:00"
}

Replace Secret Tags

Replace all tags for a secret.

PUT /static/{name}/metadata/tags

Path Parameters:

Query Parameters:

Request Body:

{
  "env": "prod",
  "owner": "db"
}

Response (200): Returns the new set of tags.

Update Secret Tags

Add or remove tags for a secret using JSON Merge Patch (RFC 7396).

PATCH /static/{name}/metadata/tags

Path Parameters:

Query Parameters:

Request Body:

{
  "newTag": "value",
  "removeTag": null
}

Note: Set a tag value to null to remove it.

Response: 204 No Content

Clear Secret Tags

Remove all tags from a secret.

DELETE /static/{name}/metadata/tags

Path Parameters:

Query Parameters:

Response: 204 No Content

Folders

List Folders

Retrieve a list of folders.

GET /folders

Query Parameters:

Response (200):

{
  "data": [
    {
      "path": "/prod",
      "type": "folder",
      "metadata": {
        "id": "d1e2f3a4-5b6c-7d8e-9f0a-1b2c3d4e5f6a",
        "tags": { "env": "prod" },
        "createdAt": "2025-09-10T14:00:00-06:00"
      }
    }
  ]
}

Create Folder

Create a new folder at the specified path.

POST /folders/{name}

Path Parameters:

Query Parameters:

Response (201):

{
  "id": "b7e8b7e2-1c2d-4e8a-9e7a-2b7e8b7e2c2d",
  "path": "/example/folder",
  "createdAt": "2025-09-12T14:00:00-06:00",
  "metadata": {
    "id": "b7e8b7e2-1c2d-4e8a-9e7a-2b7e8b7e2c2d",
    "tags": {},
    "version": 1,
    "createdAt": "2025-09-12T14:00:00-06:00"
  }
}

Delete Folder

Delete a folder at the specified path.

DELETE /folders/{name}

Path Parameters:

Query Parameters:

Response: 204 No Content

Restore Folder

Restore a deleted folder and all its contents.

POST /folders/{name}/restore

Path Parameters:

Query Parameters:

Response (200): Returns the restored folder object.

Get Folder Metadata

Retrieve metadata for a specific folder.

GET /folders/{name}/metadata

Path Parameters:

Query Parameters:

Response (200):

{
  "id": "d1e2f3a4-5b6c-7d8e-9f0a-1b2c3d4e5f6a",
  "tags": { "env": "prod" },
  "createdAt": "2025-09-10T14:00:00-06:00"
}

Replace Folder Tags

Replace all tags for a folder.

PUT /folders/{name}/metadata/tags

Path Parameters:

Query Parameters:

Request Body:

{
  "env": "prod",
  "team": "platform"
}

Response (200): Returns the new set of tags.

Update Folder Tags

Add or remove tags for a folder using JSON Merge Patch (RFC 7396).

PATCH /folders/{name}/metadata/tags

Path Parameters:

Query Parameters:

Request Body:

{
  "newTag": "value",
  "removeTag": null
}

Response: 204 No Content

Clear Folder Tags

Remove all tags from a folder.

DELETE /folders/{name}/metadata/tags

Path Parameters:

Query Parameters:

Response: 204 No Content

Integrations

Integrations connect the secrets manager to external systems such as AWS and Azure. Each integration is uniquely identified by the combination of its provider type and name, both of which appear in the URL.

List Integrations

Retrieve a list of integrations across every provider.

GET /integrations

Response (200):

{
  "data": [
    {
      "id": "fae8bacd-281c-43df-a91a-a49a2a48a07c",
      "name": "my aws",
      "type": "aws",
      "createdAt": "2025-09-12T14:00:00-06:00"
    },
    {
      "id": "2fb88d4e-86c6-4002-af6d-e04f9dc647aa",
      "name": "my azure",
      "type": "azure",
      "createdAt": "2025-10-12T14:00:00-06:00"
    }
  ]
}

List Integrations by Type

Retrieve a list of integrations scoped to a single provider type.

GET /integrations/{type}

Path Parameters:

Response (200):

{
  "data": [
    {
      "id": "fae8bacd-281c-43df-a91a-a49a2a48a07c",
      "name": "my aws",
      "type": "aws",
      "createdAt": "2025-09-12T14:00:00-06:00"
    }
  ]
}

Create Integration

Create a new integration.

POST /integrations/{type}/{name}

Path Parameters:

Request Body (AWS):

{
  "type": "aws",
  "roleArn": "arn:aws:iam::123456789012:role/MyRole"
}

Request Body (Azure):

{
  "type": "azure",
  "tenantId": "00000000-0000-0000-0000-000000000000",
  "clientId": "11111111-1111-1111-1111-111111111111",
  "clientSecret": "..."
}

Response (201):

{
  "name": "my aws",
  "type": "aws",
  "config": {
    "roleArn": "arn:aws:iam::123456789012:role/MyRole",
    "externalId": "fae8bacd-281c-43df-a91a-a49a2a48a07c"
  },
  "metadata": {
    "id": "fae8bacd-281c-43df-a91a-a49a2a48a07c",
    "version": 1,
    "createdAt": "2025-09-12T14:00:00-06:00"
  }
}

Get Integration

Retrieve details for a specific integration.

GET /integrations/{type}/{name}

Path Parameters:

Response (200):

{
  "name": "my-aws",
  "type": "aws",
  "config": {
    "roleArn": "arn:aws:iam::123456789012:role/MyRole",
    "externalId": "external-id-123"
  },
  "metadata": {
    "id": "fae8bacd-281c-43df-a91a-a49a2a48a07c",
    "version": 1,
    "createdAt": "2025-09-12T14:00:00-06:00"
  }
}

Update Integration

Update an existing integration using JSON Merge Patch (RFC 7396).

PATCH /integrations/{type}/{name}

Path Parameters:

Request Body (AWS):

{
  "roleArn": "arn:aws:iam::123456789012:role/NewRole"
}

Request Body (Azure):

{
  "clientSecret": "new-client-secret"
}

Response: 204 No Content

Delete Integration

Delete an integration.

DELETE /integrations/{type}/{name}

Path Parameters:

Response: 204 No Content

List Dynamic Secrets Using Integration

Retrieve a list of dynamic secrets that use this integration.

GET /integrations/{type}/{name}/dynamic

Path Parameters:

Response (200): Returns a list of dynamic secrets with active lease counts.

Dynamic Secrets

Dynamic secrets generate temporary credentials on demand.

List Dynamic Secrets

Retrieve a list of dynamic secrets.

GET /dynamic

Query Parameters:

Response (200):

{
  "data": [
    {
      "path": "eks-role",
      "type": "dynamic-aws",
      "metadata": {
        "id": "fae8bacd-281c-43df-a91a-a49a2a48a07c",
        "createdAt": "2025-09-12T14:00:00-06:00"
      }
    },
    {
      "path": "azure/web-app",
      "type": "dynamic-azure",
      "metadata": {
        "id": "2fb88d4e-86c6-4002-af6d-e04f9dc647aa",
        "createdAt": "2025-10-12T14:00:00-06:00"
      }
    }
  ]
}

Get Dynamic Secret

Retrieve a dynamic secret's configuration.

GET /dynamic/{name}

Path Parameters:

Query Parameters:

Response (200):

{
  "path": "eks-role",
  "config": {
    "type": "aws",
    "credentialType": "assumed_role",
    "ttl": 900,
    "integrationId": "87f59af6-894d-43ea-8821-a8dde45eb4fa",
    "roleArn": "arn:aws:iam::507498906321:role/test-role-1",
    "externalId": "xyz",
    "policyArns": [
      "arn:aws:iam::aws:policy/ReadOnlyAccess"
    ],
    "policy": "{\"Version\":\"2012-10-17\",\"Statement\":[...]}",
    "groups": ["Admins", "Developers"],
    "awsTags": { "tag1": "val1" }
  },
  "metadata": {
    "id": "fae8bacd-281c-43df-a91a-a49a2a48a07c",
    "version": 1,
    "createdAt": "2025-09-12T14:00:00-06:00"
  }
}

Create Dynamic Secret

Create a new dynamic secret.

POST /dynamic/{name}

Path Parameters:

Query Parameters:

Request Body (AWS):

{
  "type": "aws",
  "integrationName": "my-aws",
  "credentialType": "assumed_role",
  "roleArn": "arn:aws:iam::123456789012:role/MyRole",
  "externalId": "external-id-123",
  "ttl": 900,
  "policyArns": ["arn:aws:iam::aws:policy/AdministratorAccess"],
  "policy": "{\"Version\":\"2012-10-17\",\"Statement\":[...]}",
  "groups": ["Developers", "Admins"],
  "awsTags": { "env": "dev", "owner": "ops" }
}

Request Body (Azure):

{
  "type": "azure",
  "integrationName": "my-azure",
  "credentialType": "service_principal_password",
  "applicationObjectId": "22222222-2222-2222-2222-222222222222",
  "ttl": 3600
}

Note: applicationObjectId is the target Azure AD app registration's Object ID (not the Application/Client ID). TTL must be between 3600 and 86400 seconds.

Response (201): Returns the created dynamic secret object.

Update Dynamic Secret

Update an existing dynamic secret using JSON Merge Patch (RFC 7396).

PATCH /dynamic/{name}

Path Parameters:

Query Parameters:

Request Body (AWS):

{
  "type": "aws",
  "ttl": 1800,
  "roleArn": "arn:aws:iam::123456789012:role/UpdatedRole"
}

Request Body (Azure):

{
  "type": "azure",
  "ttl": 7200,
  "applicationObjectId": "33333333-3333-3333-3333-333333333333"
}

Note: The type field is required. Arrays are replaced entirely, not merged element-by-element.

Response: 204 No Content

Delete Dynamic Secret

Delete a dynamic secret.

DELETE /dynamic/{name}

Path Parameters:

Query Parameters:

Response: 204 No Content

Restore Dynamic Secret

Restore a deleted dynamic secret.

POST /dynamic/{name}/restore

Path Parameters:

Query Parameters:

Response (200): Returns the restored dynamic secret object.

Generate Dynamic Credential

Generate temporary credentials from a dynamic secret.

POST /dynamic/{name}/generate

Path Parameters:

Query Parameters:

The shape of secret depends on the dynamic secret type.

Response (201) — AWS:

{
  "secret": {
    "sessionToken": "********",
    "secretAccessKey": "AKIA****",
    "accessKeyId": "********",
    "leaseId": "b7e6f8a1-9c2d-4e3a-8b7a-2d6e4f1c9a2b",
    "expiration": "2025-09-14T15:00:00-06:00"
  }
}

Response (201) — Azure:

{
  "secret": {
    "client_id": "44444444-4444-4444-4444-444444444444",
    "client_secret": "********",
    "tenant_id": "00000000-0000-0000-0000-000000000000",
    "key_id": "55555555-5555-5555-5555-555555555555",
    "leaseId": "b7e6f8a1-9c2d-4e3a-8b7a-2d6e4f1c9a2b",
    "expiration": "2025-09-14T15:00:00-06:00"
  }
}

Get Dynamic Secret Metadata

Retrieve metadata for a dynamic secret.

GET /dynamic/{name}/metadata

Path Parameters:

Query Parameters:

Response (200): Returns metadata object.

Replace Dynamic Secret Tags

Replace all tags for a dynamic secret.

PUT /dynamic/{name}/metadata/tags

Path Parameters:

Query Parameters:

Request Body:

{
  "env": "prod",
  "owner": "db"
}

Response (200): Returns the new set of tags.

Update Dynamic Secret Tags

Add or remove tags for a dynamic secret using JSON Merge Patch (RFC 7396).

PATCH /dynamic/{name}/metadata/tags

Path Parameters:

Query Parameters:

Request Body:

{
  "newTag": "value",
  "removeTag": null
}

Response: 204 No Content

Clear Dynamic Secret Tags

Remove all tags from a dynamic secret.

DELETE /dynamic/{name}/metadata/tags

Path Parameters:

Query Parameters:

Response: 204 No Content

Leases

Leases track generated dynamic credentials and their expiration.

List Leases

Retrieve leases for a dynamic secret.

GET /leases/{name}

Path Parameters:

Query Parameters:

Response (200):

{
  "data": [
    {
      "id": "1846c4e3-7c6b-4bfa-8f9e-a55a4b678d54",
      "dynamicSecretType": "aws",
      "expiration": "2025-09-12T15:00:00-06:00",
      "createdAt": "2025-09-12T14:00:00-06:00",
      "createdBy": "3b940186-58ea-4d20-9133-3da572256d2b"
    }
  ]
}

Get Lease by ID

Retrieve lease details by its unique identifier.

GET /leases/id/{id}

Path Parameters:

Response (200):

{
  "dynamicSecretId": "b7e6f8a1-9c2d-4e3a-8b7a-2d6e4f1c9a2b",
  "dynamicSecretType": "aws",
  "dynamicSecretPath": "eks-role",
  "dynamicSecretConfig": {
    "credentialType": "assumed_role",
    "roleArn": "arn:aws:iam::123456789012:role/MyRole"
  },
  "externalEntityId": "arn:aws:iam::123456789012:assumed-role/test-role-2/bt-demo",
  "expiration": "2025-09-14T15:00:00-06:00",
  "metadata": {
    "id": "b7e6f8a1-9c2d-4e3a-8b7a-2d6e4f1c9a2b",
    "createdAt": "2025-09-14T14:00:00-06:00",
    "createdBy": "3b940186-58ea-4d20-9133-3da572256d2b"
  }
}

Revoke Lease by ID

Immediately revoke an active dynamic secret's lease. The upstream credentials are destroyed at the provider and the lease record is removed.

DELETE /leases/id/{id}

Path Parameters:

Response: 204 No Content

Note: Only lease types whose credentials support active revocation are accepted. Non-revocable types (for example, AWS STS assumed-role credentials) return 400 Bad Request with error code lease_not_revocable. If the provider call to remove the credential fails, the response is 502 Bad Gateway with error code lease_revoke_failed.

Error Responses

Error Response Format:

{
  "message": "Error description",
  "code": "error_code"
}

Error Codes:

• folder_deleted — The folder has been deleted
• secret_already_exists — A secret with this path already exists
• deleted_secret_exists — A deleted secret with this path exists
• folder_already_exists — A folder with this path already exists
• deleted_folder_exists — A deleted folder with this path exists
• aws_integration_test_failed — AWS integration test failed
• azure_integration_test_failed — Azure integration test failed
• dynamic_secret_in_use — Dynamic secret cannot be deleted as it has active leases
• lease_revoke_failed — The provider failed to revoke the credential
• lease_not_revocable — The lease type does not support active revocation

Data Types

Tags

Key-value pairs for organizing resources. Keys are case-insensitive.

• Maximum 50 tags per resource
• Maximum 256 characters per value
• Set a tag value to null to remove it

Resource Names

Valid characters: a-zA-Z0-9-_@~*^%
Maximum length: 100 characters

Full Paths

Valid characters: a-zA-Z0-9-_@~*^%/
Maximum length: 500 characters

Item Types

Dynamic Secret Credential Types