Secrets Manager API

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed
  • Status: Beta

Use this API to access GitLab Secrets Manager secrets from non-CI/CD workloads.

The API mints a short-lived JSON web token (JWT) for a project or group. A client presents this token to the OpenBao backend to read secrets directly, the same way GitLab Runner reads secrets during a CI/CD job. The response includes the OpenBao connection details the client needs.

The token expires after 5 minutes. Reading a secret value also requires the principal to have the read value permission for that secret.

Create a project access token

Mints an access token for reading a project’s secrets.

POST /projects/:id/secrets_manager/access_token

Supported attributes:

Attribute Type Required Description
id integer or string Yes The ID or URL-encoded path of the project.

Example request:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/secrets_manager/access_token"

Example response:

{
  "expires_at": "2026-05-27T10:35:00Z",
  "provider": {
    "vault": {
      "server": "https://openbao.example.com",
      "namespace": "org_5/ns_42/project_99",
      "path": "secrets/kv",
      "version": "v2",
      "auth": {
        "jwt": {
          "path": "api_jwt",
          "role": "all_api",
          "token": "<JWT>"
        }
      }
    }
  }
}

Response attributes:

Attribute Type Description
expires_at string ISO 8601 timestamp when the token expires. Tokens are valid for 5 minutes.
provider.vault.server string URL of the OpenBao server to connect to.
provider.vault.namespace string OpenBao namespace that holds the project’s secrets.
provider.vault.path string Mount path of the KV secrets engine.
provider.vault.version string Version of the KV secrets engine.
provider.vault.auth.jwt.path string Mount path of the JWT authentication method.
provider.vault.auth.jwt.role string JWT authentication role to log in with.
provider.vault.auth.jwt.token string Short-lived JWT the client presents to OpenBao.

Create a group access token

Mints an access token for reading a group’s secrets.

POST /groups/:id/secrets_manager/access_token

Supported attributes:

Attribute Type Required Description
id integer or string Yes The ID or URL-encoded path of the group.

Example request:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/secrets_manager/access_token"

Example response:

{
  "expires_at": "2026-05-27T10:35:00Z",
  "provider": {
    "vault": {
      "server": "https://openbao.example.com",
      "namespace": "org_5/group_42",
      "path": "secrets/kv",
      "version": "v2",
      "auth": {
        "jwt": {
          "path": "api_jwt",
          "role": "all_api",
          "token": "<JWT>"
        }
      }
    }
  }
}

The response attributes are the same as for Create a project access token, with provider.vault.namespace scoped to the group.