Create Federation Rule

Requires an OAuth access token with the org:admin scope, from ant auth login --scope org:admin or a workload identity federation rule; Admin API keys are not accepted. See Manage WIF with the Admin API.

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.

anthropic-betastring

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.

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.

anthropic-versionstring

The version of the Claude API you want to use.

Read more about versioning and our version history here.

The version of the Claude API you want to use.

Read more about versioning and our version history here.

Request body

applies_to_all_workspacesboolean

When true, enable this rule for every workspace in the org (including workspaces created later).

attributesobject nullable

CEL expressions {name: expr} extracting named values from claims. Not yet supported; any non-empty value is rejected with 400.

descriptionstring nullable

Optional free-text description.

issuer_idstring required

Tagged ID of the federation issuer.

namestring required

Slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409.

oauth_scopestring required

Space-separated OAuth scopes. OAuth callers may only set workspace:developer or workspace:inference; other scopes (such as org:admin) require a Console session.

token_lifetime_secondsinteger

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_idstring nullable

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.

Example request

{
  "target": {
    "service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK"
  }
}

Response

Successful Response

applies_to_all_workspacesboolean required

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_atstring date-time nullable required

If set, this rule is archived and rejects token exchange.

archived_by_actor_idstring nullable required

Tagged ID (user_/svac_) of the actor that archived this rule.

attributesobject nullable required

CEL expressions extracting named values from claims. Not yet supported; always null.

created_atstring date-time required

When this rule was created.

created_by_actor_idstring nullable required

Tagged ID (user_/svac_) of the actor that created this rule.

descriptionstring nullable required

Optional free-text description.

idstring required

Tagged ID of the federation rule.

issuer_idstring required

Tagged ID of the issuer whose tokens this rule accepts.

issuer_namestring nullable required

Issuer's display name at read time.

namestring required

Admin-chosen slug identifier.

oauth_scopestring required

Space-separated OAuth scopes granted on the minted token.

token_lifetime_secondsinteger required

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' required

updated_atstring date-time required

When this rule was last updated.

updated_by_actor_idstring nullable required

Tagged ID (user_/svac_) of the actor that last updated this rule.

workspace_idstring nullable required

Legacy single-workspace binding. Prefer workspace_ids and the /federation_rules/{federation_rule_id}/workspaces sub-resource for managing workspace enablement.

workspace_idsstring[] required

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 response

{
  "created_at": "2024-10-30T23:58:27.427722Z",
  "id": "fdrl_01SDCCSbTxrXDpWc1phhtcfK",
  "name": "prod-deploy-pipeline",
  "target": {
    "service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK"
  },
  "updated_at": "2024-10-30T23:58:27.427722Z"
}

Create Federation Rule

Headers

Request body

Example request

Response

Example response

Changes