Federated Identity

This endpoint is used to register, update, search or delete OIDC federated identity credentials. Federated identity lets an external OIDC issuer (for example GitHub Actions) call the Terrakube API directly, without a stored Personal Access Token or Team Token.

Federated identity credentials are instance-wide, not scoped to an organization. Only a superuser can create, update, or delete them, even though they are managed from an organization's Settings > Federated Credentials tab in the UI.

Entity fields:

Path	Type	Description
data.type	string	Should be "federated"
data.attributes.name	string	Name for the federated credential. A team with this exact name must exist to grant it permissions.
data.attributes.issuerUrl	string	OIDC token issuer URL, e.g. https://token.actions.githubusercontent.com
data.attributes.audience	string	Expected aud claim, e.g. api://Terrakube

Example:

POST /api/v1/federated

{
    "data": {
        "type": "federated",
        "attributes": {
            "name": "github-actions",
            "issuerUrl": "https://token.actions.githubusercontent.com",
            "audience": "api://Terrakube"
        }
    }
}

Supported Operations

POST /api/v1/federated

Register a new federated identity credential.

Request Body

Name	Type	Description
name*	String	Federated credential name
issuerUrl*	String	OIDC token issuer URL
audience*	String	Expected token audience

GET /api/v1/federated

List all federated identity credentials.

GET /api/v1/federated/{federatedId}

Get a single federated identity credential.

PATCH /api/v1/federated/{federatedId}

Update a federated identity credential.

DELETE /api/v1/federated/{federatedId}

Delete a federated identity credential. Delete its claims first.

Claim conditions

A federated credential with no claims trusts any token from the configured issuer/audience pair. Adding one or more claim conditions requires every condition to match the incoming token before it's trusted — use these to scope trust to a specific repository, branch, or environment.

Path	Type	Description
data.type	string	Should be "federated_claim"
data.attributes.claimKey	string	OIDC claim name, e.g. repository, repository_owner, ref, sub
data.attributes.claimValue	string	Required value for that claim. Matches if the claim is a string equal to this value, or a list containing it.

POST /api/v1/federated/${FEDERATED_ID}/claims

{
    "data": {
        "type": "federated_claim",
        "attributes": {
            "claimKey": "repository",
            "claimValue": "terrakube-io/terrakube"
        }
    }
}

POST /api/v1/federated/{federatedId}/claims

Add a claim condition to a federated identity credential.

GET /api/v1/federated/{federatedId}/claims

List the claim conditions on a federated identity credential.

DELETE /api/v1/federated/{federatedId}/claims/{claimId}

Delete a claim condition.