postRegister identity provider

Required capabilityidentity_providers.manage

Authentication: Send Authorization: Bearer <access_token>.

Registers a federated OIDC identity provider for an enterprise or platform-operator workspace. Discovery is resolved from issuer_uri; jwks_uri is optional and must match the discovery document when supplied. For an enterprise onboarded with its own identity stack (first-access method enterprise_idp) the body is scope_ref, issuer_uri, client_id and webhook_receiver_url only, and it registers that stack instead: a resumable saga (IdP row, issuer probe, the backend’s service account, identity and command subscriptions) that answers its ledger and replays missing steps on a repeat call. On production registration and deletion return HTTP 409 with code=state_conflict and data.reason=not_supported: identity providers are registered by seed there.

Parameters

Name Location Type Required Description and constraints
Idempotency-Key header string No Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying. minLength: 1; maxLength: 128

Request

Required request body.

Request body schema

At least one alternative must match.

Request body schema: alternative 1

Field Type Required Description and constraints
client_id string Yes minLength: 1
issuer_uri string Yes format: uri
scope_ref string Yes pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
webhook_receiver_url string Yes format: uri

Additional fields are not accepted.

Request body schema: alternative 2

Field Type Required Description and constraints
allowed_clock_skew_seconds integer or null No
auto_jit_provision boolean No default: true
claim_mapping object Yes No additional fields
client_id string Yes minLength: 1
client_secret_ref string or null No
issuer_uri string Yes format: uri
jwks_uri string or null No
link_by_verified_email boolean No default: false
protocol "oidc" Yes
scope_ref string Yes pattern: ^(enterprises|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Additional fields are not accepted.

Request body schema: alternative 2.allowed_clock_skew_seconds

At least one alternative must match.

Request body schema: alternative 2.allowed_clock_skew_seconds: alternative 1

Type: integer. minimum: 0; maximum: 9007199254740991

Request body schema: alternative 2.allowed_clock_skew_seconds: alternative 2

Type: null.

Request body schema: alternative 2.claim_mapping
Field Type Required Description and constraints
auth_context object[] No
display_name string or null No
email string or null No
external_subject string Yes minLength: 1
family_name string or null No
given_name string or null No
required_claims object[] No

Additional fields are not accepted.

Request body schema: alternative 2.claim_mapping.auth_context

Type: object[].

Request body schema: alternative 2.claim_mapping.auth_context item
Field Type Required Description and constraints
normalized_acr "single-factor" / "mfa-if-enrolled" / "mfa" Yes
required_acr string No minLength: 1
required_amr string[] No minItems: 1

Additional fields are not accepted.

Request body schema: alternative 2.claim_mapping.auth_context item.required_amr

Type: string[]. minItems: 1

Request body schema: alternative 2.claim_mapping.auth_context item.required_amr item

Type: string. minLength: 1

Request body schema: alternative 2.claim_mapping.display_name

At least one alternative must match.

Request body schema: alternative 2.claim_mapping.display_name: alternative 1

Type: string.

Request body schema: alternative 2.claim_mapping.display_name: alternative 2

Type: null.

Request body schema: alternative 2.claim_mapping.email

At least one alternative must match.

Request body schema: alternative 2.claim_mapping.email: alternative 1

Type: string.

Request body schema: alternative 2.claim_mapping.email: alternative 2

Type: null.

Request body schema: alternative 2.claim_mapping.family_name

At least one alternative must match.

Request body schema: alternative 2.claim_mapping.family_name: alternative 1

Type: string.

Request body schema: alternative 2.claim_mapping.family_name: alternative 2

Type: null.

Request body schema: alternative 2.claim_mapping.given_name

At least one alternative must match.

Request body schema: alternative 2.claim_mapping.given_name: alternative 1

Type: string.

Request body schema: alternative 2.claim_mapping.given_name: alternative 2

Type: null.

Request body schema: alternative 2.claim_mapping.required_claims

Type: object[].

Request body schema: alternative 2.claim_mapping.required_claims item
Field Type Required Description and constraints
claim string Yes minLength: 1
equals string or boolean Yes

Additional fields are not accepted.

Request body schema: alternative 2.claim_mapping.required_claims item.equals

At least one alternative must match.

Request body schema: alternative 2.claim_mapping.required_claims item.equals: alternative 1

Type: string.

Request body schema: alternative 2.claim_mapping.required_claims item.equals: alternative 2

Type: boolean.

Request body schema: alternative 2.client_secret_ref

At least one alternative must match.

Request body schema: alternative 2.client_secret_ref: alternative 1

Type: string.

Request body schema: alternative 2.client_secret_ref: alternative 2

Type: null.

Request body schema: alternative 2.jwks_uri

At least one alternative must match.

Request body schema: alternative 2.jwks_uri: alternative 1

Type: string. format: uri

Request body schema: alternative 2.jwks_uri: alternative 2

Type: null.

Request URL

POST
POST /identity-providers

Request Body

application/json
{
  "allowed_clock_skew_seconds": 30,
  "auto_jit_provision": false,
  "claim_mapping": {
    "display_name": "name",
    "email": "email",
    "external_subject": "sub",
    "family_name": "family_name",
    "given_name": "given_name"
  },
  "client_id": "my-oidc-client-id",
  "client_secret_ref": null,
  "issuer_uri": "https://accounts.google.com",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "link_by_verified_email": true,
  "protocol": "oidc",
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}

Responses

Response

application/json
{
  "allowed_clock_skew_seconds": 30,
  "auto_jit_provision": false,
  "claim_mapping": {
    "display_name": "name",
    "email": "email",
    "external_subject": "sub",
    "family_name": "family_name",
    "given_name": "given_name"
  },
  "client_id": "my-oidc-client-id",
  "client_secret_ref": null,
  "created_at": "2026-05-01T10:00:00Z",
  "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
  "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "issuer_uri": "https://accounts.google.com",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "link_by_verified_email": true,
  "protocol": "oidc",
  "resource": "identity_provider",
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "status": "active",
  "updated_at": "2026-05-01T10:00:00Z"
}

Resource created successfully.

Response 201 schema

Content type: application/json.

application/json body

At least one alternative must match.

application/json body: alternative 1
Field Type Required Description and constraints
allowed_clock_skew_seconds integer or null No
auto_jit_provision boolean Yes
claim_mapping object Yes No additional fields
client_id string Yes minLength: 1
client_secret_ref string or null No
created_at string Yes format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
etag string Yes minLength: 1
id string Yes format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
issuer_uri string Yes format: uri
jwks_uri string or null No
last_probe_at string or null No
last_probe_ok boolean or null No
link_by_verified_email boolean Yes
protocol "oidc" Yes
resource "identity_provider" Yes
scope_ref string Yes pattern: ^(enterprises|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
status "active" / "suspended" Yes
updated_at string Yes format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Additional fields are not accepted.

application/json body: alternative 1.allowed_clock_skew_seconds

At least one alternative must match.

application/json body: alternative 1.allowed_clock_skew_seconds: alternative 1

Type: integer. minimum: 0; maximum: 9007199254740991

application/json body: alternative 1.allowed_clock_skew_seconds: alternative 2

Type: null.

application/json body: alternative 1.claim_mapping
Field Type Required Description and constraints
auth_context object[] No
display_name string or null No
email string or null No
external_subject string Yes minLength: 1
family_name string or null No
given_name string or null No
required_claims object[] No

Additional fields are not accepted.

application/json body: alternative 1.claim_mapping.auth_context

Type: object[].

application/json body: alternative 1.claim_mapping.auth_context item
Field Type Required Description and constraints
normalized_acr "single-factor" / "mfa-if-enrolled" / "mfa" Yes
required_acr string No minLength: 1
required_amr string[] No minItems: 1

Additional fields are not accepted.

application/json body: alternative 1.claim_mapping.auth_context item.required_amr

Type: string[]. minItems: 1

application/json body: alternative 1.claim_mapping.auth_context item.required_amr item

Type: string. minLength: 1

application/json body: alternative 1.claim_mapping.display_name

At least one alternative must match.

application/json body: alternative 1.claim_mapping.display_name: alternative 1

Type: string.

application/json body: alternative 1.claim_mapping.display_name: alternative 2

Type: null.

application/json body: alternative 1.claim_mapping.email

At least one alternative must match.

application/json body: alternative 1.claim_mapping.email: alternative 1

Type: string.

application/json body: alternative 1.claim_mapping.email: alternative 2

Type: null.

application/json body: alternative 1.claim_mapping.family_name

At least one alternative must match.

application/json body: alternative 1.claim_mapping.family_name: alternative 1

Type: string.

application/json body: alternative 1.claim_mapping.family_name: alternative 2

Type: null.

application/json body: alternative 1.claim_mapping.given_name

At least one alternative must match.

application/json body: alternative 1.claim_mapping.given_name: alternative 1

Type: string.

application/json body: alternative 1.claim_mapping.given_name: alternative 2

Type: null.

application/json body: alternative 1.claim_mapping.required_claims

Type: object[].

application/json body: alternative 1.claim_mapping.required_claims item
Field Type Required Description and constraints
claim string Yes minLength: 1
equals string or boolean Yes

Additional fields are not accepted.

application/json body: alternative 1.claim_mapping.required_claims item.equals

At least one alternative must match.

application/json body: alternative 1.claim_mapping.required_claims item.equals: alternative 1

Type: string.

application/json body: alternative 1.claim_mapping.required_claims item.equals: alternative 2

Type: boolean.

application/json body: alternative 1.client_secret_ref

At least one alternative must match.

application/json body: alternative 1.client_secret_ref: alternative 1

Type: string.

application/json body: alternative 1.client_secret_ref: alternative 2

Type: null.

application/json body: alternative 1.jwks_uri

At least one alternative must match.

application/json body: alternative 1.jwks_uri: alternative 1

Type: string. format: uri

application/json body: alternative 1.jwks_uri: alternative 2

Type: null.

application/json body: alternative 1.last_probe_at

At least one alternative must match.

application/json body: alternative 1.last_probe_at: alternative 1

Type: string. format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

application/json body: alternative 1.last_probe_at: alternative 2

Type: null.

application/json body: alternative 1.last_probe_ok

At least one alternative must match.

application/json body: alternative 1.last_probe_ok: alternative 1

Type: boolean.

application/json body: alternative 1.last_probe_ok: alternative 2

Type: null.

application/json body: alternative 2
Field Type Required Description and constraints
command_subscription_id string or null Yes
enterprise_id string Yes format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
failing_step "identity_provider" / "probe" / "service_account" / "identity_subscription" / "command_subscription" or null Yes
identity_provider_id string or null Yes
identity_subscription_id string or null Yes
probe_ok boolean Yes
ready boolean Yes
service_principal_id string or null Yes
updated_at string Yes format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Additional fields are not accepted.

application/json body: alternative 2.command_subscription_id

At least one alternative must match.

application/json body: alternative 2.command_subscription_id: alternative 1

Type: string. format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

application/json body: alternative 2.command_subscription_id: alternative 2

Type: null.

application/json body: alternative 2.failing_step

At least one alternative must match.

application/json body: alternative 2.failing_step: alternative 1

Type: "identity_provider" / "probe" / "service_account" / "identity_subscription" / "command_subscription".

application/json body: alternative 2.failing_step: alternative 2

Type: null.

application/json body: alternative 2.identity_provider_id

At least one alternative must match.

application/json body: alternative 2.identity_provider_id: alternative 1

Type: string. format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

application/json body: alternative 2.identity_provider_id: alternative 2

Type: null.

application/json body: alternative 2.identity_subscription_id

At least one alternative must match.

application/json body: alternative 2.identity_subscription_id: alternative 1

Type: string. format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

application/json body: alternative 2.identity_subscription_id: alternative 2

Type: null.

application/json body: alternative 2.service_principal_id

At least one alternative must match.

application/json body: alternative 2.service_principal_id: alternative 1

Type: string. format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

application/json body: alternative 2.service_principal_id: alternative 2

Type: null.

Response 400 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
code string Yes
data object No No additional fields
details object No Additional fields allowed
message string Yes

Additional fields are not accepted.

application/json body.data
Field Type Required Description and constraints
acr_values string No RFC 9470 step-up challenge (insufficient_user_authentication).
blockers object[] No For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.
code string No For legal refusals: the document code the refusal is about.
max_age string No RFC 9470 step-up challenge (insufficient_user_authentication).
max_source_amount object No For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum. No additional fields
min_source_amount object No For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included. No additional fields
published_version string No For document_version_superseded: the version currently published.
reason string No Typed refinement of code, from the failing service's contract.
resource string No Resource kind a resource_not_found refers to.
retry_after_ms integer No Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0
source string No For not_admissible: the gate that denied (verification, lifecycle, policy, compliance).

Additional fields are not accepted.

application/json body.data.blockers

For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.

Type: object[].

application/json body.data.blockers item
Field Type Required Description and constraints
description string Yes
type "non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" Yes
assets object[] No minItems: 1
count integer No minimum: 0; maximum: 9007199254740991

Additional fields are not accepted.

application/json body.data.blockers item.assets

Type: object[]. minItems: 1

application/json body.data.blockers item.assets item
Field Type Required Description and constraints
asset string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
kind "balance" / "held" / "owed" / "unsettled" Yes

Additional fields are not accepted.

application/json body.data.max_source_amount

For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

application/json body.data.min_source_amount

For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

Response 401 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
code string Yes
data object No No additional fields
details object No Additional fields allowed
message string Yes

Additional fields are not accepted.

application/json body.data
Field Type Required Description and constraints
acr_values string No RFC 9470 step-up challenge (insufficient_user_authentication).
blockers object[] No For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.
code string No For legal refusals: the document code the refusal is about.
max_age string No RFC 9470 step-up challenge (insufficient_user_authentication).
max_source_amount object or null No For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum. No additional fields
min_source_amount object No For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included. No additional fields
published_version string No For document_version_superseded: the version currently published.
reason string No Typed refinement of code, from the failing service's contract.
resource string No Resource kind a resource_not_found refers to.
retry_after_ms integer or null No Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0
source string No For not_admissible: the gate that denied (verification, lifecycle, policy, compliance).

Additional fields are not accepted.

application/json body.data.blockers

For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.

Type: object[].

application/json body.data.blockers item
Field Type Required Description and constraints
description string Yes
type "non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" Yes
assets object[] No minItems: 1
count integer No minimum: 0; maximum: 9007199254740991

Additional fields are not accepted.

application/json body.data.blockers item.assets

Type: object[]. minItems: 1

application/json body.data.blockers item.assets item
Field Type Required Description and constraints
asset string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
kind "balance" / "held" / "owed" / "unsettled" Yes

Additional fields are not accepted.

application/json body.data.max_source_amount

For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

application/json body.data.min_source_amount

For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

Response 403 schema

Content type: application/json.

See response 401 schema.

Response 409 schema

Content type: application/json.

See response 401 schema.

Response 500 schema

Content type: application/json.

See response 401 schema.

Response 502 schema

Content type: application/json.

See response 400 schema.

Response 503 schema

Content type: application/json.

See response 400 schema.