# Secrets

[Buildkite secrets](/docs/pipelines/security/secrets/buildkite-secrets) is an encrypted key-value store secrets management service. Secrets are scoped within a [Buildkite cluster](/docs/pipelines/security/clusters) and can be accessed by agents within that cluster using the [`buildkite-agent secret get` command](/docs/agent/cli/reference/secret) or by defining `secrets` within a pipeline YAML configuration. Access to secrets is controlled through [access policies](/docs/pipelines/security/secrets/buildkite-secrets/access-policies).

## Secret data model



| `id` | ID of the secret |
| --- | --- |
| `graphql_id` | GraphQL ID of the secret |
| `key` | A unique identifier for the secret |
| `value` | The encrypted secret value. This field is never returned by the API |
| `description` | Description of the secret |
| `policy` | YAML policy defining access rules for the secret |
| `url` | Canonical API URL of the secret |
| `cluster_url` | API URL of the cluster this secret belongs to |
| `created_at` | When the secret was created |
| `created_by` | User who created the secret |
| `updated_at` | When the secret was last updated |
| `updated_by` | User who last updated the secret |
| `last_read_at` | When the secret was last accessed by a build |
| `organization` | Organization this secret belongs to |



## List secrets

Returns a [paginated list](/docs/rest-api#pagination) of a cluster's secrets.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/secrets"
```

```json
[
  {
    "id": "9bf7650d-52ba-40e6-a18e-7a34a109f8bc",
    "key": "MY_SECRET",
    "description": "My secret description",
    "policy": "- pipeline_slug: my-pipeline\n  build_branch: main",
    "created_at": "2025-10-01T06:51:21.067Z",
    "created_by": {
      "id": "01987d6e-44a6-415c-85d1-c247c938e8d5",
      "name": "Staff",
      "email": "test+staff@example.com"
    },
    "updated_at": "2025-10-01T06:51:21.173Z",
    "updated_by": null,
    "last_read_at": null,
    "url": "http://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/secrets/9bf7650d-52ba-40e6-a18e-7a34a109f8bc",
    "cluster_url": "http://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}",
    "organization": {
      "id": "0198e45b-c0d5-4a0b-8e37-e140af750d2d",
      "slug": "my-org",
      "url": "http://api.buildkite.com/v2/organizations/my-org",
      "web_url": "http://buildkite.com/my-org"
    }
  }
]
```

Required scope: `read_secret_details`

Success response: `200 OK`

## Get a secret

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/secrets/{id}"
```

```json
{
  "id": "9bf7650d-52ba-40e6-a18e-7a34a109f8bc",
  "key": "MY_SECRET",
  "description": "My secret description",
  "policy": "- pipeline_slug: my-pipeline\n  build_branch: main",
  "created_at": "2025-10-01T06:51:21.067Z",
  "created_by": {
    "id": "01987d6e-44a6-415c-85d1-c247c938e8d5",
    "name": "Staff",
    "email": "test+staff@example.com"
  },
  "updated_at": "2025-10-01T06:51:21.173Z",
  "updated_by": null,
  "last_read_at": null,
  "url": "http://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/secrets/9bf7650d-52ba-40e6-a18e-7a34a109f8bc",
  "cluster_url": "http://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}",
  "organization": {
    "id": "0198e45b-c0d5-4a0b-8e37-e140af750d2d",
    "slug": "my-org",
    "url": "http://api.buildkite.com/v2/organizations/my-org",
    "web_url": "http://buildkite.com/my-org"
  }
}
```

Required scope: `read_secret_details`

Success response: `200 OK`

## Create a secret

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/secrets" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "MY_SECRET",
    "value": "secret-value",
    "description": "My secret description",
    "policy": "- pipeline_slug: my-pipeline\n  build_branch: main"
  }'
```

```json
{
  "id": "30f93dd5-bc23-4a14-8ad3-fd1920ea8eb5",
  "key": "MY_SECRET",
  "description": "My secret description",
  "policy": "- pipeline_slug: my-pipeline\n  build_branch: main",
  "created_at": "2025-10-01T07:43:38.648Z",
  "created_by": {
    "id": "01987d6e-44a6-415c-85d1-c247c938e8d5",
    "name": "Staff",
    "email": "test+staff@example.com"
  },
  "updated_at": "2025-10-01T07:43:38.708Z",
  "updated_by": null,
  "last_read_at": null,
  "url": "http://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/secrets/30f93dd5-bc23-4a14-8ad3-fd1920ea8eb5",
  "cluster_url": "http://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}",
  "organization": {
    "id": "0198e45b-c0d5-4a0b-8e37-e140af750d2d",
    "slug": "my-org",
    "url": "http://api.buildkite.com/v2/organizations/my-org",
    "web_url": "http://buildkite.com/my-org"
  }
}
```

Required [request body properties](/docs/api#request-body-properties):



| `key` | A unique identifier for the secret. Must start with a letter and only contain letters, numbers, and underscores. Cannot start with `buildkite` or `bk` (case insensitive). Maximum length is 255 characters. Must be unique within the cluster _Example:_ `"MY_SECRET"` |
| --- | --- |



Optional [request body properties](/docs/api#request-body-properties):



| `value` | The secret value to encrypt and store. Must be less than 8 kilobytes. Cannot be blank. _Example:_ `"secret-value"` |
| --- | --- |
| `description` | A description of the secret _Example:_ `"My secret description"` |
| `policy` | YAML policy defining access rules. See [Access policies for Buildkite secrets](/docs/pipelines/security/secrets/buildkite-secrets/access-policies) for details on policy structure and available claims _Example:_ `"- pipeline_slug: my-pipeline\n build_branch: main"` |



Required scope: `write_secrets`

Success response: `201 Created`

## Update a secret's description and access policy

Updates a secret's description and access policy. To update its value instead, see [Update a secret's value](#update-a-secrets-value).

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/secrets/{id}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "policy": "- pipeline_slug: my-pipeline\n  build_branch: production"
  }'
```

```json
{
  "id": "30f93dd5-bc23-4a14-8ad3-fd1920ea8eb5",
  "key": "MY_SECRET",
  "description": "Updated description",
  "policy": "- pipeline_slug: my-pipeline\n  build_branch: production",
  "created_at": "2025-10-01T07:43:38.648Z",
  "created_by": {
    "id": "01987d6e-44a6-415c-85d1-c247c938e8d5",
    "name": "Staff",
    "email": "test+staff@example.com"
  },
  "updated_at": "2025-10-01T07:43:46.949Z",
  "updated_by": {
    "id": "01987d6e-44a6-415c-85d1-c247c938e8d5",
    "name": "Staff",
    "email": "test+staff@example.com"
  },
  "last_read_at": null,
  "url": "http://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/secrets/30f93dd5-bc23-4a14-8ad3-fd1920ea8eb5",
  "cluster_url": "http://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}",
  "organization": {
    "id": "0198e45b-c0d5-4a0b-8e37-e140af750d2d",
    "slug": "my-org",
    "url": "http://api.buildkite.com/v2/organizations/my-org",
    "web_url": "http://buildkite.com/my-org"
  }
}
```

Optional [request body properties](/docs/api#request-body-properties):



| `description` | A description of the secret _Example:_ `"Updated description"` |
| --- | --- |
| `policy` | YAML policy defining access rules. See [Access policies for Buildkite secrets](/docs/pipelines/security/secrets/buildkite-secrets/access-policies) for details on policy structure and available claims _Example:_ `"- pipeline_slug: my-pipeline\n build_branch: production"` |



Unpermitted [request body properties](/docs/api#request-body-properties):



| `key` | Attempting to update the `key` parameter returns an error: `"The key parameter cannot be updated."` |
| --- | --- |
| `value` | Attempting to update the `value` parameter returns an error: `"The value parameter cannot be updated on this endpoint."` |



Required scope: `write_secrets`

Success response: `200 OK`

## Update a secret's value

Updates a secret's encrypted value only. To update the secret's other details, see [Update a secret's description and access policy](#update-a-secrets-description-and-access-policy).

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/secrets/{id}/value" \
  -H "Content-Type: application/json" \
  -d '{"value": "new-secret-value"}'
```

```json
{
  "id": "30f93dd5-bc23-4a14-8ad3-fd1920ea8eb5",
  "key": "MY_SECRET",
  "description": "Updated description",
  "policy": "- pipeline_slug: my-pipeline\n  build_branch: production",
  "created_at": "2025-10-01T07:43:38.648Z",
  "created_by": {
    "id": "01987d6e-44a6-415c-85d1-c247c938e8d5",
    "name": "Staff",
    "email": "test+staff@example.com"
  },
  "updated_at": "2025-10-01T07:44:09.081Z",
  "updated_by": {
    "id": "01987d6e-44a6-415c-85d1-c247c938e8d5",
    "name": "Staff",
    "email": "test+staff@example.com"
  },
  "last_read_at": null,
  "url": "http://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/secrets/30f93dd5-bc23-4a14-8ad3-fd1920ea8eb5",
  "cluster_url": "http://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}",
  "organization": {
    "id": "0198e45b-c0d5-4a0b-8e37-e140af750d2d",
    "slug": "my-org",
    "url": "http://api.buildkite.com/v2/organizations/my-org",
    "web_url": "http://buildkite.com/my-org"
  }
}
```

Required [request body properties](/docs/api#request-body-properties):



| `value` | The new secret value to encrypt and store. Must be less than 8 kilobytes. Cannot be blank. _Example:_ `"new-secret-value"` |
| --- | --- |



Required scope: `write_secrets`

Success response: `200 OK`

## Delete a secret

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/secrets/{id}"
```

Required scope: `write_secrets`

Success response: `204 No Content`