Secrets

Buildkite secrets is an encrypted key-value store secrets management service. Secrets are scoped within a Buildkite cluster and can be accessed by agents within that cluster using the buildkite-agent secret get command or by defining secrets within a pipeline YAML configuration. Access to secrets is controlled through 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 of a cluster's secrets.

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

[
  {
    "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

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

{
  "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

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"
  }'

{
  "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:

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:

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 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.

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"
  }'

{
  "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:

description A description of the secret
Example: "Updated description"
policy YAML policy defining access rules. See Access policies for Buildkite secrets for details on policy structure and available claims
Example: "- pipeline_slug: my-pipeline\n build_branch: production"

Unpermitted 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.

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"}'

{
  "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:

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

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