Federation rules
Federation rules API methods, requests, and responses for RawTree Cloud and RawTree BYOC.
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
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:
# 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.
[
{
"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.
POST /v1/federation-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:
# 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.
{
"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.
GET /v1/federation-rules/{id}
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:
# 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.
{
"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.
PUT /v1/federation-rules/{id}
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:
# 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.
{
"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.
DELETE /v1/federation-rules/{id}
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:
# 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.
nullErrors: 400, 401, 403, 404, 409. See API errors.