Page history
Create Federation Rule
api/admin/federation_rules/create
History
api/admin/federation_rules/create Changed · +43 / -26 lines
# Create Federation Rule ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Create Federation Rule ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
from line 1
---- -title: Create Federation Rule -url: https://platform.claude.com/docs/en/api/admin/federation_rules/create ---- +# Create Federation Rule -## Create Federation Rule +**POST** `/v1/organizations/federation_rules` -**post** `/v1/organizations/federation_rules` - Create a federation rule owned by your organization. The referenced issuer and the target service account must already exist
from line 19
`workspace:inference`; other scopes require a Console session. Admin API keys are not accepted. -### Header Parameters +## Headers - `"anthropic-beta": optional array of string`
from line 27
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta. -### Body Parameters +## Body parameters - `issuer_id: string` Tagged ID of the federation issuer. -- `match: object { audience, claims, condition, subject_prefix }` +- `match: object` Conditions the verified JWT must satisfy for this rule to apply. At least one of `subject_prefix` (other than a wildcard-only value like `*`), `claims`, or `condition` is required; `audience` alone is not sufficient.
from line 41
Exact match against the `aud` claim (any element if array). When omitted, the JWT's `aud` must still equal Anthropic's expected audience for the issuer; setting this field overrides that default. + maxLength: 1024 + - `claims: optional map[string] or null` Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims.
from line 51
CEL expression over claims for logic the structural fields can't express. Must evaluate to a boolean and may reference only the `claims` variable; a constant-true expression (such as `true`) is rejected with 400. + maxLength: 4096 + - `subject_prefix: optional string or null` Match the verified JWT `sub` claim. Exact match unless the value ends with `*`, in which case it is a prefix match. Example: `repo:my-org/my-repo:ref:refs/heads/main`. + maxLength: 1024 + - `name: string` Slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409. + maxLength: 255, minLength: 1 + - `oauth_scope: string` Space-separated OAuth scopes. OAuth callers may only set `workspace:developer` or `workspace:inference`; other scopes (such as `org:admin`) require a Console session. -- `target: object { service_account_id, type, service_account_name }` + minLength: 1 +- `target: object` + Identity that tokens minted via this rule act as. Currently always a `service_account` target. - `service_account_id: string`
from line 81
- `type: "service_account"` - - `"service_account"` - - `service_account_name: optional string or null` Service account's display name at read time. Ignored on writes.
from line 97
Optional free-text description. + maxLength: 2000 + - `token_lifetime_seconds: optional number` Lifetime in seconds for access tokens minted via this rule (60-86400). Defaults to 3600 (1h). Minted tokens are capped at `max(60, min(this value, 2 × remaining assertion validity))` seconds. + maximum: 86400, minimum: 60 + - `workspace_id: optional string or null` Tagged ID of the workspace to enable this rule for. Required unless `applies_to_all_workspaces` is true. Additional workspaces can be added via the `/federation_rules/{federation_rule_id}/workspaces` sub-resource. -### Returns +## Returns -- `FederationRule object { id, applies_to_all_workspaces, archived_at, 17 more }` +- `FederationRule object` Authorization rule binding an external OIDC identity to Anthropic.
from line 136
If set, this rule is archived and rejects token exchange. + format: date-time + - `archived_by_actor_id: string or null` Tagged ID (`user_`/`svac_`) of the actor that archived this rule.
from line 150
When this rule was created. + format: date-time + - `created_by_actor_id: string or null` Tagged ID (`user_`/`svac_`) of the actor that created this rule.
from line 168
Issuer's display name at read time. - - `match: object { audience, claims, condition, subject_prefix }` + - `match: object` Conditions the verified JWT must satisfy for this rule to apply. All populated matcher fields must pass.
from line 176
Exact match against the `aud` claim (any element if array). When omitted, the JWT's `aud` must still equal Anthropic's expected audience for the issuer; setting this field overrides that default. + maxLength: 1024 + - `claims: optional map[string] or null` Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims.
from line 186
CEL expression over claims for logic the structural fields can't express. Must evaluate to a boolean and may reference only the `claims` variable; a constant-true expression (such as `true`) is rejected with 400. + maxLength: 4096 + - `subject_prefix: optional string or null` Match the verified JWT `sub` claim. Exact match unless the value ends with `*`, in which case it is a prefix match. Example: `repo:my-org/my-repo:ref:refs/heads/main`. + maxLength: 1024 + - `name: string` Admin-chosen slug identifier.
from line 202
Space-separated OAuth scopes granted on the minted token. - - `target: object { service_account_id, type, service_account_name }` + - `target: object` Identity that tokens minted via this rule act as. Currently always a `service_account` target.
from line 212
- `type: "service_account"` - - `"service_account"` - - `service_account_name: optional string or null` Service account's display name at read time. Ignored on writes.
from line 222
- `type: "federation_rule"` - - `"federation_rule"` + default: federation_rule - `updated_at: string` When this rule was last updated. + format: date-time + - `updated_by_actor_id: string or null` Tagged ID (`user_`/`svac_`) of the actor that last updated this rule.
from line 242
Tagged IDs of the workspaces this rule is enabled for. May be empty for older rules that only carry the legacy `workspace_id` binding. Ignored at exchange time when `applies_to_all_workspaces` is true (the list may still be non-empty). -### Example +## Example -```http +```bash curl https://api.anthropic.com/v1/organizations/federation_rules \ -H 'Content-Type: application/json' \ -H 'anthropic-version: 2023-06-01' \
from line 261
}' ``` -#### Response +### Response (200) ```json {
api/admin/federation_rules/create First recorded · 287 lines, first recorded
## Create Federation Rule ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
The first capture of this source. The page was already there, and this is what it said.
---
title: Create Federation Rule
url: https://platform.claude.com/docs/en/api/admin/federation_rules/create
---
## Create Federation Rule
**post** `/v1/organizations/federation_rules`
Create a federation rule owned by your organization.
The referenced issuer and the target service account must already exist
in the same organization; invalid references are rejected with a 400
error. The workspace reference is validated. Membership is not checked
at rule creation: token exchange resolves a single enabled workspace per
call and is rejected unless the target service account is a member of
that workspace (it is implicitly a member of the default workspace).
Rules on well-known shared issuers (GitHub Actions, GitLab, Buildkite,
Terraform Cloud, Google) must constrain tenant identity via an
identity-bearing claim, a tenant-pinning subject prefix (such as
`repo:YOUR_ORG/...`), or a CEL condition referencing one of those
identity claims (e.g. `claims.repository_owner`). OAuth callers may only
manage rules whose `oauth_scope` is `workspace:developer` or
`workspace:inference`; other scopes require a Console session. Admin API
keys are not accepted.
### Header Parameters
- `"anthropic-beta": optional array of string`
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
### Body Parameters
- `issuer_id: string`
Tagged ID of the federation issuer.
- `match: object { audience, claims, condition, subject_prefix }`
Conditions the verified JWT must satisfy for this rule to apply. At least one of `subject_prefix` (other than a wildcard-only value like `*`), `claims`, or `condition` is required; `audience` alone is not sufficient.
- `audience: optional string or null`
Exact match against the `aud` claim (any element if array). When omitted, the JWT's `aud` must still equal Anthropic's expected audience for the issuer; setting this field overrides that default.
- `claims: optional map[string] or null`
Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims.
- `condition: optional string or null`
CEL expression over claims for logic the structural fields can't express. Must evaluate to a boolean and may reference only the `claims` variable; a constant-true expression (such as `true`) is rejected with 400.
- `subject_prefix: optional string or null`
Match the verified JWT `sub` claim. Exact match unless the value ends with `*`, in which case it is a prefix match. Example: `repo:my-org/my-repo:ref:refs/heads/main`.
- `name: string`
Slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409.
- `oauth_scope: string`
Space-separated OAuth scopes. OAuth callers may only set `workspace:developer` or `workspace:inference`; other scopes (such as `org:admin`) require a Console session.
- `target: object { service_account_id, type, service_account_name }`
Identity that tokens minted via this rule act as. Currently always a `service_account` target.
- `service_account_id: string`
Tagged ID of the service account to mint tokens for.
- `type: "service_account"`
- `"service_account"`
- `service_account_name: optional string or null`
Service account's display name at read time. Ignored on writes.
- `applies_to_all_workspaces: optional boolean`
When true, enable this rule for every workspace in the org (including workspaces created later).
- `attributes: optional map[string] or null`
CEL expressions `{name: expr}` extracting named values from claims. Not yet supported; any non-empty value is rejected with 400.
- `description: optional string or null`
Optional free-text description.
- `token_lifetime_seconds: optional number`
Lifetime in seconds for access tokens minted via this rule (60-86400). Defaults to 3600 (1h). Minted tokens are capped at `max(60, min(this value, 2 × remaining assertion validity))` seconds.
- `workspace_id: optional string or null`
Tagged ID of the workspace to enable this rule for. Required unless `applies_to_all_workspaces` is true. Additional workspaces can be added via the `/federation_rules/{federation_rule_id}/workspaces` sub-resource.
### Returns
- `FederationRule object { id, applies_to_all_workspaces, archived_at, 17 more }`
Authorization rule binding an external OIDC identity to Anthropic.
Evaluates the match conditions and mints an OAuth access token for the
resolved target, scoped to a single workspace where the rule is enabled
(chosen by the caller at exchange time when the rule is enabled for more
than one). For rules enabled via `workspace_ids` or
`applies_to_all_workspaces`, the target service account must be a member
of that workspace (it is implicitly a member of the default workspace);
rules carrying only the legacy `workspace_id` binding do not enforce
this.
- `id: string`
Tagged ID of the federation rule.
- `applies_to_all_workspaces: boolean`
When true, this rule is enabled for every workspace in the org (including ones created after the rule). `workspace_ids` is ignored at exchange time.
- `archived_at: string or null`
If set, this rule is archived and rejects token exchange.
- `archived_by_actor_id: string or null`
Tagged ID (`user_`/`svac_`) of the actor that archived this rule.
- `attributes: map[string] or null`
CEL expressions extracting named values from claims. Not yet supported; always null.
- `created_at: string`
When this rule was created.
- `created_by_actor_id: string or null`
Tagged ID (`user_`/`svac_`) of the actor that created this rule.
- `description: string or null`
Optional free-text description.
- `issuer_id: string`
Tagged ID of the issuer whose tokens this rule accepts.
- `issuer_name: string or null`
Issuer's display name at read time.
- `match: object { audience, claims, condition, subject_prefix }`
Conditions the verified JWT must satisfy for this rule to apply. All populated matcher fields must pass.
- `audience: optional string or null`
Exact match against the `aud` claim (any element if array). When omitted, the JWT's `aud` must still equal Anthropic's expected audience for the issuer; setting this field overrides that default.
- `claims: optional map[string] or null`
Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims.
- `condition: optional string or null`
CEL expression over claims for logic the structural fields can't express. Must evaluate to a boolean and may reference only the `claims` variable; a constant-true expression (such as `true`) is rejected with 400.
- `subject_prefix: optional string or null`
Match the verified JWT `sub` claim. Exact match unless the value ends with `*`, in which case it is a prefix match. Example: `repo:my-org/my-repo:ref:refs/heads/main`.
- `name: string`
Admin-chosen slug identifier.
- `oauth_scope: string`
Space-separated OAuth scopes granted on the minted token.
- `target: object { service_account_id, type, service_account_name }`
Identity that tokens minted via this rule act as. Currently always a `service_account` target.
- `service_account_id: string`
Tagged ID of the service account to mint tokens for.
- `type: "service_account"`
- `"service_account"`
- `service_account_name: optional string or null`
Service account's display name at read time. Ignored on writes.
- `token_lifetime_seconds: number`
Lifetime in seconds of access tokens minted via this rule. Minted tokens are capped at `max(60, min(this value, 2 × remaining assertion validity))` seconds.
- `type: "federation_rule"`
- `"federation_rule"`
- `updated_at: string`
When this rule was last updated.
- `updated_by_actor_id: string or null`
Tagged ID (`user_`/`svac_`) of the actor that last updated this rule.
- `workspace_id: string or null`
Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement.
- `workspace_ids: array of string`
Tagged IDs of the workspaces this rule is enabled for. May be empty for older rules that only carry the legacy `workspace_id` binding. Ignored at exchange time when `applies_to_all_workspaces` is true (the list may still be non-empty).
### Example
```http
curl https://api.anthropic.com/v1/organizations/federation_rules \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
-d '{
"issuer_id": "issuer_id",
"match": {},
"name": "x",
"oauth_scope": "x",
"target": {
"service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"type": "service_account"
}
}'
```
#### Response
```json
{
"id": "fdrl_01SDCCSbTxrXDpWc1phhtcfK",
"applies_to_all_workspaces": true,
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"attributes": {
"foo": "string"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"issuer_id": "issuer_id",
"issuer_name": "issuer_name",
"match": {
"audience": "audience",
"claims": {
"foo": "string"
},
"condition": "condition",
"subject_prefix": "subject_prefix"
},
"name": "prod-deploy-pipeline",
"oauth_scope": "oauth_scope",
"target": {
"service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"type": "service_account",
"service_account_name": "service_account_name"
},
"token_lifetime_seconds": 0,
"type": "federation_rule",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id",
"workspace_id": "workspace_id",
"workspace_ids": [
"string"
]
}
```