# Federation rules (/docs/reference/api/federation-rules) Federation rules [#federation-rules] All rule methods require an organization administrator. Select the organization and cluster by name. Define which workloads can exchange a provider token for a RawTree Cloud or RawTree BYOC access token. Each rule selects a cluster, principal, default database, and permissions. GET `/v1/federation-rules` [#get-v1federation-rules] List stored rules. 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. Parameters: | Field | Location | Type | Required | Notes | | -------------- | -------- | ------ | -------- | ----- | | `organization` | query | string | Yes | — | | `cluster` | query | string | Yes | — | Request: ```bash # List stored rules. Requires a organization administrator using a user session or OAuth. curl -X GET "https://api.rawtree.com/v1/federation-rules?organization=team_alpha&cluster=production" \ -H "Authorization: Bearer $RAWTREE_USER_TOKEN" ``` Expected response: **HTTP 200**. ```json [ { "name": "github-reader", "issuer_id": "11111111-1111-4111-8111-111111111111", "allowed_audiences": [ "rawtree" ], "claim_conditions": { "sub": "repo:acme/analytics:ref:refs/heads/main" }, "principal_type": "service_account", "principal_id": "11111111-1111-4111-8111-111111111111", "permission": "read_only", "database": "analytics", "enabled": true, "id": "11111111-1111-4111-8111-111111111111", "organization_id": "22222222-2222-4222-8222-222222222222", "cluster_id": "33333333-3333-4333-8333-333333333333", "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/federation-rules` [#post-v1federation-rules] Store a rule 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 | | ------------------- | -------- | --------------- | -------- | --------------------------------------------------------------------------------------- | | `organization` | query | string | Yes | — | | `cluster` | query | string | Yes | — | | `name` | body | string | Yes | — | | `description` | body | string or null | No | — | | `issuer_id` | body | string | Yes | — | | `allowed_audiences` | body | array of string | Yes | At least one exact audience. A future token must match one entry. | | `claim_conditions` | body | object | Yes | Exact, top-level string claims. All conditions must match; no expressions or wildcards. | | `principal_type` | body | PrincipalType | Yes | — | | `principal_id` | body | string | Yes | — | | `permission` | body | string or null | No | Exactly one of permission or database\_roles is required, as for API keys. | | `database_roles` | body | array or null | No | — | | `database` | body | string | Yes | Default database, not a restriction on database-role grants. | | `enabled` | body | boolean | Yes | Whether matching workloads can exchange assertions under this rule. | Request: ```bash # Store a rule configuration. Does not fetch keys or enable authentication. curl -X POST "https://api.rawtree.com/v1/federation-rules?organization=team_alpha&cluster=production" \ -H "Authorization: Bearer $RAWTREE_USER_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "github-reader", "issuer_id": "11111111-1111-4111-8111-111111111111", "allowed_audiences": [ "rawtree" ], "claim_conditions": { "sub": "repo:acme/analytics:ref:refs/heads/main" }, "principal_type": "service_account", "principal_id": "11111111-1111-4111-8111-111111111111", "permission": "read_only", "database": "analytics", "enabled": true }' ``` Expected response: **HTTP 200**. ```json { "name": "github-reader", "issuer_id": "11111111-1111-4111-8111-111111111111", "allowed_audiences": [ "rawtree" ], "claim_conditions": { "sub": "repo:acme/analytics:ref:refs/heads/main" }, "principal_type": "service_account", "principal_id": "11111111-1111-4111-8111-111111111111", "permission": "read_only", "database": "analytics", "enabled": true, "id": "11111111-1111-4111-8111-111111111111", "organization_id": "22222222-2222-4222-8222-222222222222", "cluster_id": "33333333-3333-4333-8333-333333333333", "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/federation-rules/{id}` [#get-v1federation-rulesid] Get a stored rule configuration.. 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 | | -------------- | -------- | ------ | -------- | ----- | | `organization` | query | string | Yes | — | | `cluster` | query | string | Yes | — | Request: ```bash # Get a stored rule configuration. curl -X GET "https://api.rawtree.com/v1/federation-rules/11111111-1111-4111-8111-111111111111?organization=team_alpha&cluster=production" \ -H "Authorization: Bearer $RAWTREE_USER_TOKEN" ``` Expected response: **HTTP 200**. ```json { "name": "github-reader", "issuer_id": "11111111-1111-4111-8111-111111111111", "allowed_audiences": [ "rawtree" ], "claim_conditions": { "sub": "repo:acme/analytics:ref:refs/heads/main" }, "principal_type": "service_account", "principal_id": "11111111-1111-4111-8111-111111111111", "permission": "read_only", "database": "analytics", "enabled": true, "id": "11111111-1111-4111-8111-111111111111", "organization_id": "22222222-2222-4222-8222-222222222222", "cluster_id": "33333333-3333-4333-8333-333333333333", "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/federation-rules/{id}` [#put-v1federation-rulesid] Replace the complete configuration. Omitted optional fields are cleared.. 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 | | ------------------- | -------- | --------------- | -------- | --------------------------------------------------------------------------------------- | | `organization` | query | string | Yes | — | | `cluster` | query | string | Yes | — | | `name` | body | string | Yes | — | | `description` | body | string or null | No | — | | `issuer_id` | body | string | Yes | — | | `allowed_audiences` | body | array of string | Yes | At least one exact audience. A future token must match one entry. | | `claim_conditions` | body | object | Yes | Exact, top-level string claims. All conditions must match; no expressions or wildcards. | | `principal_type` | body | PrincipalType | Yes | — | | `principal_id` | body | string | Yes | — | | `permission` | body | string or null | No | Exactly one of permission or database\_roles is required, as for API keys. | | `database_roles` | body | array or null | No | — | | `database` | body | string | Yes | Default database, not a restriction on database-role grants. | | `enabled` | body | boolean | Yes | Whether matching workloads can exchange assertions under this rule. | Request: ```bash # Replace the complete configuration. Omitted optional fields are cleared. curl -X PUT "https://api.rawtree.com/v1/federation-rules/11111111-1111-4111-8111-111111111111?organization=team_alpha&cluster=production" \ -H "Authorization: Bearer $RAWTREE_USER_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "github-reader", "issuer_id": "11111111-1111-4111-8111-111111111111", "allowed_audiences": [ "rawtree" ], "claim_conditions": { "sub": "repo:acme/analytics:ref:refs/heads/main" }, "principal_type": "service_account", "principal_id": "11111111-1111-4111-8111-111111111111", "permission": "read_only", "database": "analytics", "enabled": true }' ``` Expected response: **HTTP 200**. ```json { "name": "github-reader", "issuer_id": "11111111-1111-4111-8111-111111111111", "allowed_audiences": [ "rawtree" ], "claim_conditions": { "sub": "repo:acme/analytics:ref:refs/heads/main" }, "principal_type": "service_account", "principal_id": "11111111-1111-4111-8111-111111111111", "permission": "read_only", "database": "analytics", "enabled": true, "id": "11111111-1111-4111-8111-111111111111", "organization_id": "22222222-2222-4222-8222-222222222222", "cluster_id": "33333333-3333-4333-8333-333333333333", "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/federation-rules/{id}` [#delete-v1federation-rulesid] Delete a stored rule configuration.. 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 | | -------------- | -------- | ------ | -------- | ----- | | `organization` | query | string | Yes | — | | `cluster` | query | string | Yes | — | Request: ```bash # Delete a stored rule configuration. curl -X DELETE "https://api.rawtree.com/v1/federation-rules/11111111-1111-4111-8111-111111111111?organization=team_alpha&cluster=production" \ -H "Authorization: Bearer $RAWTREE_USER_TOKEN" ``` Expected response: **HTTP 200**. ```json null ``` Errors: `400`, `401`, `403`, `404`, `409`. See [API errors](/docs/reference/errors).