CI OIDC API
6 endpoints. Request and response schemas are described on the schemas page; the other tags are listed in the API index.
Endpoints
POST /api/v1/auth/oidc/exchange
Exchange a CI ID token for an access token
Trade the OpenID Connect ID token of a CI job (GitHub Actions, GitLab CI, ...) for a short-lived deploy token of the service account a trust policy maps it to. No credentials are needed: the ID token is the credential. Its signature is verified against the issuer's published keys, and its issuer, audience, expiry and claims are checked against the enabled trust policies. Every refusal of the token is the same 401, whatever the cause. Rate-limited per client address.
Authentication: none (public endpoint).
Request body (required)
application/json: object
| Field | Type | Required | Description |
|---|---|---|---|
policy | string | no | Name of the trust policy to use; by default the oldest policy that accepts the token. |
token | string | yes | The CI job's ID token (a JWT). |
Responses
| Status | Description | Body |
|---|---|---|
200 | Token issued | application/json: OIDCExchangeResponse |
400 | Malformed request | application/json: Error |
401 | Token not accepted | application/json: Error |
429 | Too many requests | application/json: Error |
GET /api/v1/oidc-trust-policies
List CI OIDC trust policies
List the trust policies of the CI OIDC token exchange, by name (admin only).
Responses
| Status | Description | Body |
|---|---|---|
200 | Trust policies | application/json: object |
400 | Invalid request | application/json: Error |
403 | Admin access required | - |
Fields of the 200 response (application/json):
| Field | Type | Required | Description |
|---|---|---|---|
data | array of OIDCTrustPolicy | no | - |
POST /api/v1/oidc-trust-policies
Create CI OIDC trust policy
Trust the ID tokens of a CI system that match the conditions and map them to a service account (admin only). See POST /api/v1/auth/oidc/exchange.
Request body (required)
application/json: object
| Field | Type | Required | Description |
|---|---|---|---|
audience | string | yes | The aud value the CI job requests; matched exactly. |
conditions | array of OIDCCondition | yes | All conditions must hold. Policies of a shared issuer (GitHub Actions, gitlab.com) need one on an identity claim such as repository, sub or project_path, whose patterns do not start with a wildcard. |
enabled | boolean | no | Default: true. |
issuer | string (uri) | yes | Issuer URL exactly as in the iss claim of the tokens, for example https://token.actions.githubusercontent.com or https://gitlab.com. Must be https and pass the outbound-request (SSRF) check. |
name | string | yes | Unique name: 1-64 letters, digits, dot, dash or underscore. |
service_account_id | string (uuid) | yes | - |
token_ttl_seconds | integer | no | Lifetime of exchanged tokens. Default: 900. Minimum: 60. Maximum: 3600. |
Responses
| Status | Description | Body |
|---|---|---|
201 | Trust policy created | application/json: OIDCTrustPolicy |
400 | Invalid request, including an issuer that fails the outbound-request check or a missing identity condition for a shared issuer | application/json: Error |
403 | Admin access required | - |
409 | A trust policy with this name exists | application/json: Error |
GET /api/v1/oidc-trust-policies/{id}
Get CI OIDC trust policy
Get one trust policy (admin only).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
200 | Trust policy | application/json: OIDCTrustPolicy |
403 | Admin access required | - |
404 | Trust policy not found | - |
PATCH /api/v1/oidc-trust-policies/{id}
Update CI OIDC trust policy
Change any field of a trust policy; omitted fields keep their value (admin only). Tokens already exchanged stay valid until they expire (at most one hour).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | - |
Request body (required)
application/json: object
| Field | Type | Required | Description |
|---|---|---|---|
audience | string | no | The aud value the CI job requests; matched exactly. |
conditions | array of OIDCCondition | no | All conditions must hold. Policies of a shared issuer (GitHub Actions, gitlab.com) need one on an identity claim such as repository, sub or project_path, whose patterns do not start with a wildcard. |
enabled | boolean | no | Default: true. |
issuer | string (uri) | no | Issuer URL exactly as in the iss claim of the tokens, for example https://token.actions.githubusercontent.com or https://gitlab.com. Must be https and pass the outbound-request (SSRF) check. |
name | string | no | Unique name: 1-64 letters, digits, dot, dash or underscore. |
service_account_id | string (uuid) | no | - |
token_ttl_seconds | integer | no | Lifetime of exchanged tokens. Default: 900. Minimum: 60. Maximum: 3600. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Trust policy updated | application/json: OIDCTrustPolicy |
400 | Invalid request | application/json: Error |
403 | Admin access required | - |
404 | Trust policy not found | - |
409 | A trust policy with this name exists | application/json: Error |
DELETE /api/v1/oidc-trust-policies/{id}
Delete CI OIDC trust policy
Delete a trust policy (admin only). Tokens already exchanged stay valid until they expire (at most one hour); disable the service account to cut them off at once.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
204 | Trust policy deleted | - |
403 | Admin access required | - |
404 | Trust policy not found | - |