# Federation issuers (/docs/reference/api/federation-issuers)



Federation issuers [#federation-issuers]

All issuer methods require an organization administrator. Use the organization UUID in the path.

Define the identity providers that your organization trusts. Issuers belong to an organization. Rules select an issuer and restrict the workloads that can authenticate.

GET `/v1/organizations/{organization_id}/federation-issuers` [#get-v1organizationsorganization_idfederation-issuers]

List stored issuers. Requires a organization administrator using a user session or OAuth..

Use a user session or user OAuth token with `full_access`. API keys and workload tokens cannot use this method.

Request:

```bash
# List stored issuers. Requires a organization administrator using a user session or OAuth.
curl -X GET "https://api.rawtree.com/v1/organizations/22222222-2222-4222-8222-222222222222/federation-issuers" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"
```

Expected response: **HTTP 200**.

```json
[
  {
    "name": "github-actions",
    "issuer_url": "https://token.actions.githubusercontent.com",
    "jwks_source": "discovery",
    "id": "11111111-1111-4111-8111-111111111111",
    "organization_id": "22222222-2222-4222-8222-222222222222",
    "created_at": "2026-11-09T10:00:00Z",
    "updated_at": "2026-11-09T10:00:00Z"
  }
]
```

Errors: `400`, `401`, `403`, `404`, `409`. See [API errors](/docs/reference/errors).

POST `/v1/organizations/{organization_id}/federation-issuers` [#post-v1organizationsorganization_idfederation-issuers]

Store an issuer configuration. Does not fetch keys or enable authentication..

Use a user session or user OAuth token with `full_access`. API keys and workload tokens cannot use this method.

Parameters:

| Field         | Location | Type           | Required | Notes                                                                                                                                 |
| ------------- | -------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | body     | string         | Yes      | —                                                                                                                                     |
| `description` | body     | string or null | No       | Optional description, up to 2000 UTF-8 bytes.                                                                                         |
| `issuer_url`  | body     | string         | Yes      | HTTPS URL without credentials, query, or fragment; up to 2048 UTF-8 bytes.                                                            |
| `jwks_source` | body     | JwksSource     | No       | —                                                                                                                                     |
| `jwks_url`    | body     | string or null | No       | Required for explicit\_url; must be null or omitted for discovery. HTTPS URL without credentials or fragment; up to 2048 UTF-8 bytes. |

Request:

```bash
# Store an issuer configuration. Does not fetch keys or enable authentication.
curl -X POST "https://api.rawtree.com/v1/organizations/22222222-2222-4222-8222-222222222222/federation-issuers" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "github-actions",
  "issuer_url": "https://token.actions.githubusercontent.com",
  "jwks_source": "discovery"
}'
```

Expected response: **HTTP 200**.

```json
{
  "name": "github-actions",
  "issuer_url": "https://token.actions.githubusercontent.com",
  "jwks_source": "discovery",
  "id": "11111111-1111-4111-8111-111111111111",
  "organization_id": "22222222-2222-4222-8222-222222222222",
  "created_at": "2026-11-09T10:00:00Z",
  "updated_at": "2026-11-09T10:00:00Z"
}
```

Errors: `400`, `401`, `403`, `404`, `409`. See [API errors](/docs/reference/errors).

GET `/v1/organizations/{organization_id}/federation-issuers/{id}` [#get-v1organizationsorganization_idfederation-issuersid]

Get a stored issuer configuration..

Use a user session or user OAuth token with `full_access`. API keys and workload tokens cannot use this method.

Request:

```bash
# Get a stored issuer configuration.
curl -X GET "https://api.rawtree.com/v1/organizations/22222222-2222-4222-8222-222222222222/federation-issuers/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"
```

Expected response: **HTTP 200**.

```json
{
  "name": "github-actions",
  "issuer_url": "https://token.actions.githubusercontent.com",
  "jwks_source": "discovery",
  "id": "11111111-1111-4111-8111-111111111111",
  "organization_id": "22222222-2222-4222-8222-222222222222",
  "created_at": "2026-11-09T10:00:00Z",
  "updated_at": "2026-11-09T10:00:00Z"
}
```

Errors: `400`, `401`, `403`, `404`, `409`. See [API errors](/docs/reference/errors).

PUT `/v1/organizations/{organization_id}/federation-issuers/{id}` [#put-v1organizationsorganization_idfederation-issuersid]

Replace the complete configuration. Omitted optional fields are cleared; jwks\_source defaults to discovery..

Use a user session or user OAuth token with `full_access`. API keys and workload tokens cannot use this method.

Parameters:

| Field         | Location | Type           | Required | Notes                                                                                                                                 |
| ------------- | -------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | body     | string         | Yes      | —                                                                                                                                     |
| `description` | body     | string or null | No       | Optional description, up to 2000 UTF-8 bytes.                                                                                         |
| `issuer_url`  | body     | string         | Yes      | HTTPS URL without credentials, query, or fragment; up to 2048 UTF-8 bytes.                                                            |
| `jwks_source` | body     | JwksSource     | No       | —                                                                                                                                     |
| `jwks_url`    | body     | string or null | No       | Required for explicit\_url; must be null or omitted for discovery. HTTPS URL without credentials or fragment; up to 2048 UTF-8 bytes. |

Request:

```bash
# Replace the complete configuration. Omitted optional fields are cleared; jwks_source defaults to discovery.
curl -X PUT "https://api.rawtree.com/v1/organizations/22222222-2222-4222-8222-222222222222/federation-issuers/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "github-actions",
  "issuer_url": "https://token.actions.githubusercontent.com",
  "jwks_source": "discovery"
}'
```

Expected response: **HTTP 200**.

```json
{
  "name": "github-actions",
  "issuer_url": "https://token.actions.githubusercontent.com",
  "jwks_source": "discovery",
  "id": "11111111-1111-4111-8111-111111111111",
  "organization_id": "22222222-2222-4222-8222-222222222222",
  "created_at": "2026-11-09T10:00:00Z",
  "updated_at": "2026-11-09T10:00:00Z"
}
```

Errors: `400`, `401`, `403`, `404`, `409`. See [API errors](/docs/reference/errors).

DELETE `/v1/organizations/{organization_id}/federation-issuers/{id}` [#delete-v1organizationsorganization_idfederation-issuersid]

Delete a stored issuer configuration..

Use a user session or user OAuth token with `full_access`. API keys and workload tokens cannot use this method.

Request:

```bash
# Delete a stored issuer configuration.
curl -X DELETE "https://api.rawtree.com/v1/organizations/22222222-2222-4222-8222-222222222222/federation-issuers/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"
```

Expected response: **HTTP 200**.

```json
null
```

Errors: `400`, `401`, `403`, `404`, `409`. See [API errors](/docs/reference/errors).