Page history
Update Federation Rule
api/admin/federation_rules/update
History
api/admin/federation_rules/update Changed · +44 / -27 lines
# Update Federation Rule ## Path parameters ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Update Federation Rule ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
from line 1
---- -title: Update Federation Rule -url: https://platform.claude.com/docs/en/api/admin/federation_rules/update ---- +# Update Federation Rule -## Update Federation Rule +**POST** `/v1/organizations/federation_rules/{federation_rule_id}` -**post** `/v1/organizations/federation_rules/{federation_rule_id}` - Partially update a federation rule. `issuer_id` is immutable. `match` and `target` are replaced as whole
from line 20
`workspace:developer` or `workspace:inference`; other scopes require a Console session. Admin API keys are not accepted. -### Path Parameters +## Path parameters - `federation_rule_id: string` ID of the federation rule to update. -### Header Parameters +## Headers - `"anthropic-beta": optional array of string`
from line 34
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 - `applies_to_all_workspaces: optional boolean or null`
from line 48
Replaces the description. Omit to leave unchanged; send `null` to clear (the field is stored as an empty string). -- `match: optional object { audience, claims, condition, subject_prefix } or null` + maxLength: 2000 +- `match: optional object or null` + Does the incoming JWT qualify? All populated fields must pass; omitted fields are skipped. At least one
from line 62
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 72
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: optional string or null` Replaces the slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409. + maxLength: 255, minLength: 1 + - `oauth_scope: optional string or null` Replaces the space-separated OAuth scopes granted on minted tokens. OAuth callers may only set `workspace:developer` or `workspace:inference`; other scopes (such as `org:admin`) require a Console session. -- `target: optional object { service_account_id, type, service_account_name } or null` + minLength: 1 +- `target: optional object or null` + Bind to a fixed service account by ID. - `service_account_id: string`
from line 102
- `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 110
Replaces the lifetime in seconds for access tokens minted via this rule (60-86400). 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` Replaces the existing single workspace enablement (the previous one is removed). Rejected with 400 if the rule is enabled for more than one workspace; use the `/federation_rules/{federation_rule_id}/workspaces` sub-resource instead. -### 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 143
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 157
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 175
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 183
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 193
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 209
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 219
- `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 229
- `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 249
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/$FEDERATION_RULE_ID \ -H 'Content-Type: application/json' \ -H 'anthropic-version: 2023-06-01' \
from line 259
-d '{}' ``` -#### Response +### Response (200) ```json {
api/admin/federation_rules/update First recorded · 285 lines, first recorded
## Update Federation Rule ### Path Parameters ### 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: Update Federation Rule
url: https://platform.claude.com/docs/en/api/admin/federation_rules/update
---
## Update Federation Rule
**post** `/v1/organizations/federation_rules/{federation_rule_id}`
Partially update a federation rule.
`issuer_id` is immutable. `match` and `target` are replaced as whole
objects when set. Referenced service accounts and workspaces must exist
in your organization; invalid references are rejected with a 400 error.
Archived rules cannot be updated; this returns 400. Create a new rule
instead. 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`). On these issuers the
requirement is re-checked on every update; if an existing rule's stored
match does not yet constrain tenant identity, any update (even a rename
or description change) must also supply a conforming `match` in the same
request. 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.
### Path Parameters
- `federation_rule_id: string`
ID of the federation rule to update.
### 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
- `applies_to_all_workspaces: optional boolean or null`
When true, enables this rule for every workspace in the org (including workspaces created later). Setting `false` is rejected with 400 if no workspace would remain enabled; a rule with only a legacy `workspace_id` binding continues to mint.
- `attributes: optional map[string] or null`
Replaces the CEL expressions `{name: expr}` extracting named values from claims. Send null to clear them. Not yet supported; any non-empty value is rejected with 400.
- `description: optional string or null`
Replaces the description. Omit to leave unchanged; send `null` to clear (the field is stored as an empty string).
- `match: optional object { audience, claims, condition, subject_prefix } or null`
Does the incoming JWT qualify?
All populated fields must pass; omitted fields are skipped. 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: optional string or null`
Replaces the slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409.
- `oauth_scope: optional string or null`
Replaces the space-separated OAuth scopes granted on minted tokens. OAuth callers may only set `workspace:developer` or `workspace:inference`; other scopes (such as `org:admin`) require a Console session.
- `target: optional object { service_account_id, type, service_account_name } or null`
Bind to a fixed service account by ID.
- `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: optional number or null`
Replaces the lifetime in seconds for access tokens minted via this rule (60-86400). Minted tokens are capped at `max(60, min(this value, 2 × remaining assertion validity))` seconds.
- `workspace_id: optional string or null`
Replaces the existing single workspace enablement (the previous one is removed). Rejected with 400 if the rule is enabled for more than one workspace; use the `/federation_rules/{federation_rule_id}/workspaces` sub-resource instead.
### 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/$FEDERATION_RULE_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
-d '{}'
```
#### 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"
]
}
```