> For the complete documentation index, see [llms.txt](https://docs.terrakube.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terrakube.io/2.33.0/api/methods/federated.md).

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

{% hint style="warning" %}
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.
{% endhint %}

### 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:

```json
POST /api/v1/federated

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

### Supported Operations

<mark style="color:green;">`POST`</mark> `/api/v1/federated`

Register a new federated identity credential.

#### Request Body

| Name                                        | Type   | Description               |
| ------------------------------------------- | ------ | ------------------------- |
| name<mark style="color:red;">\*</mark>      | String | Federated credential name |
| issuerUrl<mark style="color:red;">\*</mark> | String | OIDC token issuer URL     |
| audience<mark style="color:red;">\*</mark>  | String | Expected token audience   |

<mark style="color:blue;">`GET`</mark> `/api/v1/federated`

List all federated identity credentials.

<mark style="color:blue;">`GET`</mark> `/api/v1/federated/{federatedId}`

Get a single federated identity credential.

<mark style="color:purple;">`PATCH`</mark> `/api/v1/federated/{federatedId}`

Update a federated identity credential.

<mark style="color:red;">`DELETE`</mark> `/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. |

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

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

<mark style="color:green;">`POST`</mark> `/api/v1/federated/{federatedId}/claims`

Add a claim condition to a federated identity credential.

<mark style="color:blue;">`GET`</mark> `/api/v1/federated/{federatedId}/claims`

List the claim conditions on a federated identity credential.

<mark style="color:red;">`DELETE`</mark> `/api/v1/federated/{federatedId}/claims/{claimId}`

Delete a claim condition.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.terrakube.io/2.33.0/api/methods/federated.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.