ProudAuthDocs
Documentation/API reference

Federation

Upstream identity providers (OIDC and social), federated sign-in callbacks and linked identities. 27 operations

Expand an endpoint for authentication, parameters, request fields and responses.

GET/api/v1/realms/{realm}/federation/{connection}/callback+

Upstream callback (query response mode)

Upstream authorization response endpoint registered with the identity provider. When the realm has a login UI the browser is redirected (303) to it with transaction_id (and federation_error); a pending link confirmation code travels in the URL fragment (federation_link_code). Headless realms without a login UI receive the outcome as JSON. Returns 404 feature_disabled when federation is not configured.

AuthenticationPublic / endpoint-specific credentialsTrust classtransaction-boundPermissionsSee operation description

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
connectionpathYesFederation connection (identity provider) alias.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}
statequery—state
{"type":"string"}
codequery—code
{"type":"string","x-secret":true}
errorquery—error
{"type":"string"}

Responses

200 OK

application/json

{
  "oneOf": [
    {
      "type": "object",
      "title": "CallbackOutcome",
      "properties": {
        "transaction_id": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "ok",
            "error"
          ]
        },
        "error": {
          "type": "string"
        }
      },
      "required": [
        "status"
      ]
    },
    {
      "type": "object",
      "title": "LinkPendingConfirmation",
      "properties": {
        "status": {
          "type": "string",
          "const": "link_pending_confirmation"
        },
        "link_code": {
          "type": "string",
          "x-secret": true,
          "description": "Single-use code for POST /me/linked-identities/confirm."
        }
      },
      "required": [
        "status",
        "link_code"
      ]
    }
  ]
}

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
303 Redirect to the realm login UI.

Response headers

{
  "Location": {
    "$ref": "#/components/headers/Location"
  }
}
400 Malformed request, invalid JSON (duplicate members, unknown fields, wrong types), invalid cursor or invalid transaction (code invalid_request, transaction_invalid, invalid_proof, invitation_invalid).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
429 Rate limited (code rate_limited). Includes Retry-After; never discloses per-user state.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
503 Load shedding, realm unavailable or dependency failure (code unavailable, upstream_unavailable). May include Retry-After.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  }
}

Operation federationCallbackGet · Schema definitions · OpenAPI contract

POST/api/v1/realms/{realm}/federation/{connection}/callback+

Upstream callback (form_post response mode)

Upstream authorization response endpoint registered with the identity provider. When the realm has a login UI the browser is redirected (303) to it with transaction_id (and federation_error); a pending link confirmation code travels in the URL fragment (federation_link_code). Headless realms without a login UI receive the outcome as JSON. Returns 404 feature_disabled when federation is not configured.

AuthenticationPublic / endpoint-specific credentialsTrust classtransaction-boundPermissionsSee operation description

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
connectionpathYesFederation connection (identity provider) alias.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}

Request body

application/x-www-form-urlencoded · required

FieldTypeRequiredDescription
statestring—
codeone-time secretstring—
errorstring—
Complete request schema
{
  "type": "object",
  "description": "At most 64 KiB.",
  "properties": {
    "state": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "x-secret": true
    },
    "error": {
      "type": "string"
    }
  }
}

Responses

200 OK

application/json

{
  "oneOf": [
    {
      "type": "object",
      "title": "CallbackOutcome",
      "properties": {
        "transaction_id": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "ok",
            "error"
          ]
        },
        "error": {
          "type": "string"
        }
      },
      "required": [
        "status"
      ]
    },
    {
      "type": "object",
      "title": "LinkPendingConfirmation",
      "properties": {
        "status": {
          "type": "string",
          "const": "link_pending_confirmation"
        },
        "link_code": {
          "type": "string",
          "x-secret": true,
          "description": "Single-use code for POST /me/linked-identities/confirm."
        }
      },
      "required": [
        "status",
        "link_code"
      ]
    }
  ]
}

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
303 Redirect to the realm login UI.

Response headers

{
  "Location": {
    "$ref": "#/components/headers/Location"
  }
}
400 Malformed request, invalid JSON (duplicate members, unknown fields, wrong types), invalid cursor or invalid transaction (code invalid_request, transaction_invalid, invalid_proof, invitation_invalid).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
413 Body exceeds limits.max_body_bytes (code payload_too_large).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
429 Rate limited (code rate_limited). Includes Retry-After; never discloses per-user state.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
503 Load shedding, realm unavailable or dependency failure (code unavailable, upstream_unavailable). May include Retry-After.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  }
}

Operation federationCallbackPost · Schema definitions · OpenAPI contract

GET/api/v1/realms/{realm}/me/linked-identities+

List own linked external identities

Returns an empty list when federation is not configured.

AuthenticationaccountTokenTrust classuser-self-servicePermissionsSee operation description

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}
cursorquery—Opaque cursor from a previous page (next_cursor). Cursors are HMAC-bound to the realm and listing.
{"type":"string"}
limitquery—Page size; defaults to limits.default_page_size and is capped at limits.max_page_size.
{"type":"integer","minimum":1}

Responses

200 OK

application/json

FieldTypeRequiredDescription
itemsarrayYes
next_cursorstring—Opaque cursor for the next page; empty on the last page (API-004).

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
503 Load shedding, realm unavailable or dependency failure (code unavailable, upstream_unavailable). May include Retry-After.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  }
}

Operation listMyLinkedIdentities · Schema definitions · OpenAPI contract

DELETE/api/v1/realms/{realm}/me/linked-identities/{id}+

Unlink an external identity

Requires recent authentication. The last viable sign-in method cannot be removed.

AuthenticationaccountTokenTrust classuser-self-servicePermissionsSee operation description

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
idpathYesResource identifier.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}

Responses

204 No Content

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
503 Load shedding, realm unavailable or dependency failure (code unavailable, upstream_unavailable). May include Retry-After.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  }
}

Operation unlinkMyIdentity · Schema definitions · OpenAPI contract

GET/api/v1/realms/{realm}/identity-providers+

List identity provider connections

AuthenticationadminTokenTrust classadministrativePermissionsrealm.identity_providers.read

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}
cursorquery—Opaque cursor from a previous page (next_cursor). Cursors are HMAC-bound to the realm and listing.
{"type":"string"}
limitquery—Page size; defaults to limits.default_page_size and is capped at limits.max_page_size.
{"type":"integer","minimum":1}

Responses

200 OK

application/json

FieldTypeRequiredDescription
itemsarrayYes
next_cursorstring—Opaque cursor for the next page; empty on the last page (API-004).

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
503 Load shedding, realm unavailable or dependency failure (code unavailable, upstream_unavailable). May include Retry-After.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  }
}

Operation listIdentityProviders · Schema definitions · OpenAPI contract

POST/api/v1/realms/{realm}/identity-providers+

Create an identity provider connection

AuthenticationadminTokenTrust classadministrativePermissionsrealm.identity_providers.write

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}
Idempotency-Keyheader—Actor/realm/route-bound idempotency key (API-005) for POST requests, at most 255 characters (422 otherwise), kept for 24 hours; only a digest of the key is stored. The request is identified by its method, exact path and body: a replay with the same path and body returns the stored status and response with Idempotent-Replayed: true; the same key with a different body or another path on the same route (another resource) returns 422 idempotency_key_reused; a request still in progress returns 409. Only successful responses are recorded: when the original request failed (an error or a status of 400 or above) the key is released and a retry runs again. Responses containing one-time secrets (members such as client_secret, token, api_key, access_token, refresh_token, id_token, recovery_codes, secret or webhook_secrets) are never stored or replayed (409 with original_status).
{"type":"string","maxLength":255}

Request body

application/json · required

FieldTypeRequiredDescription
adapterstring—Defaults to oidc. Built-in adapters (FED-002): oidc (generic OpenID Connect), github (OAuth 2.0 with the REST user API; numeric account ID as subject; only verified emails), google (fixed issuer https://accounts.google.com; allowed_tenants restricts to Workspace domains through the hd claim), microsoft (Entra ID work and school accounts: issuer https://login.microsoftonline.com/{tenant}/v2.0 selected by tid, allowed_tenants required; its email claim is never treated as verified, so trusted_verified_email linking is refused). Deployments can register further adapters in code; unknown names are refused.
aliasstringYesLower-case letters, digits and dashes (2..63). Part of the registered callback URL; cannot be changed.
claim_mappingoneOf—
client_secretone-time secretstring,null—Upstream client secret (write-only; stored encrypted and never returned, see has_client_secret). On PUT, omit to keep the current secret; an empty string clears it.
configIdentityProviderConfigYes
display_namestringYes
issuerstring—Upstream issuer; required for OIDC connections. May contain {tenant} for multi-tenant issuers. Cannot change while identities are linked.
jit_default_role_idstring—
jit_provisioningboolean—
linking_policystring—
verify_existing | trusted_verified_email | create_only
organization_idstring—
statestring—
active | disabled
trust_upstream_mfaboolean—
Complete request schema
{
  "additionalProperties": false,
  "properties": {
    "adapter": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_-]{0,31}$",
      "description": "Defaults to oidc. Built-in adapters (FED-002): oidc (generic OpenID Connect), github (OAuth 2.0 with the REST user API; numeric account ID as subject; only verified emails), google (fixed issuer https://accounts.google.com; allowed_tenants restricts to Workspace domains through the hd claim), microsoft (Entra ID work and school accounts: issuer https://login.microsoftonline.com/{tenant}/v2.0 selected by tid, allowed_tenants required; its email claim is never treated as verified, so trusted_verified_email linking is refused). Deployments can register further adapters in code; unknown names are refused."
    },
    "alias": {
      "type": "string",
      "description": "Lower-case letters, digits and dashes (2..63). Part of the registered callback URL; cannot be changed."
    },
    "claim_mapping": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/ClaimMapping"
        },
        {
          "type": "null"
        }
      ]
    },
    "client_secret": {
      "type": [
        "string",
        "null"
      ],
      "x-secret": true,
      "format": "password",
      "description": "Upstream client secret (write-only; stored encrypted and never returned, see has_client_secret). On PUT, omit to keep the current secret; an empty string clears it."
    },
    "config": {
      "$ref": "#/components/schemas/IdentityProviderConfig"
    },
    "display_name": {
      "type": "string",
      "maxLength": 100
    },
    "issuer": {
      "type": "string",
      "description": "Upstream issuer; required for OIDC connections. May contain {tenant} for multi-tenant issuers. Cannot change while identities are linked."
    },
    "jit_default_role_id": {
      "type": "string"
    },
    "jit_provisioning": {
      "type": "boolean"
    },
    "linking_policy": {
      "type": "string",
      "enum": [
        "verify_existing",
        "trusted_verified_email",
        "create_only"
      ]
    },
    "organization_id": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ]
    },
    "trust_upstream_mfa": {
      "type": "boolean"
    }
  },
  "type": "object",
  "required": [
    "alias",
    "config",
    "display_name"
  ]
}

Responses

201 Created

application/json

FieldTypeRequiredDescription
adapterstringYesThe provider adapter; saml for a SAML connection (FED-014).
aliasstringYes
claim_mappingClaimMappingYes
configIdentityProviderConfigYes
created_atstringYes
display_namestringYes
has_client_secretbooleanYes
idstringYes
issuerstringYes
jit_default_role_idstring—
jit_provisioningbooleanYes
kindstringYesoidc, oauth2_social or saml. SAML connections are listed here; PUT answers 409 for them (manage them under /saml/connections) and POST /identity-providers/{id}/test reports SAML certificate diagnostics without contacting the provider.
linking_policystringYes
mapping_revisionintegerYes
organization_idstring—
statestringYes
trust_upstream_mfabooleanYes
updated_atstringYes
versionintegerYes

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "ETag": {
    "$ref": "#/components/headers/ETag"
  },
  "Idempotent-Replayed": {
    "$ref": "#/components/headers/Idempotent-Replayed"
  }
}
400 Malformed request, invalid JSON (duplicate members, unknown fields, wrong types), invalid cursor or invalid transaction (code invalid_request, transaction_invalid, invalid_proof, invitation_invalid).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
413 Body exceeds limits.max_body_bytes (code payload_too_large).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
415 Wrong Content-Type (code unsupported_media_type).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
422 Validation failed (code validation_failed, password_policy, idempotency_key_reused); errors maps fields to messages.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
503 Load shedding, realm unavailable or dependency failure (code unavailable, upstream_unavailable). May include Retry-After.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  }
}

Operation createIdentityProvider · Schema definitions · OpenAPI contract

GET/api/v1/realms/{realm}/identity-providers/{id}+

Get an identity provider connection

AuthenticationadminTokenTrust classadministrativePermissionsrealm.identity_providers.read

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
idpathYesResource identifier.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}

Responses

200 OK

application/json

FieldTypeRequiredDescription
adapterstringYesThe provider adapter; saml for a SAML connection (FED-014).
aliasstringYes
claim_mappingClaimMappingYes
configIdentityProviderConfigYes
created_atstringYes
display_namestringYes
has_client_secretbooleanYes
idstringYes
issuerstringYes
jit_default_role_idstring—
jit_provisioningbooleanYes
kindstringYesoidc, oauth2_social or saml. SAML connections are listed here; PUT answers 409 for them (manage them under /saml/connections) and POST /identity-providers/{id}/test reports SAML certificate diagnostics without contacting the provider.
linking_policystringYes
mapping_revisionintegerYes
organization_idstring—
statestringYes
trust_upstream_mfabooleanYes
updated_atstringYes
versionintegerYes

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "ETag": {
    "$ref": "#/components/headers/ETag"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
503 Load shedding, realm unavailable or dependency failure (code unavailable, upstream_unavailable). May include Retry-After.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  }
}

Operation getIdentityProvider · Schema definitions · OpenAPI contract

PUT/api/v1/realms/{realm}/identity-providers/{id}+

Replace an identity provider connection

Replaces the connection's settings (If-Match required: 428 without, 412 when stale), validated as at creation. alias may be omitted (kept) but cannot change (422 on alias: it is part of the registered callback URL). issuer, and the protocol implied by adapter, cannot change while identities are linked to the connection (409 on issuer or adapter; use a reviewed migration). client_secret omitted keeps the stored secret, an empty string removes it and a value replaces it; claim_mapping omitted keeps the current mapping, and a changed mapping increases mapping_revision. SAML connections are managed at /saml/connections (409 here). Audited as federation.provider.updated.

AuthenticationadminTokenTrust classadministrativePermissionsrealm.identity_providers.write

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
idpathYesResource identifier.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}
If-MatchheaderYesExpected resource version from the ETag. Required: missing returns 428, stale returns 412.
{"type":"string","examples":["W/\"v12\""]}

Request body

application/json · required

FieldTypeRequiredDescription
adapterstring—Defaults to oidc. Built-in adapters (FED-002): oidc (generic OpenID Connect), github (OAuth 2.0 with the REST user API; numeric account ID as subject; only verified emails), google (fixed issuer https://accounts.google.com; allowed_tenants restricts to Workspace domains through the hd claim), microsoft (Entra ID work and school accounts: issuer https://login.microsoftonline.com/{tenant}/v2.0 selected by tid, allowed_tenants required; its email claim is never treated as verified, so trusted_verified_email linking is refused). Deployments can register further adapters in code; unknown names are refused.
aliasstringYesLower-case letters, digits and dashes (2..63). Part of the registered callback URL; cannot be changed.
claim_mappingoneOf—
client_secretone-time secretstring,null—Upstream client secret (write-only; stored encrypted and never returned, see has_client_secret). On PUT, omit to keep the current secret; an empty string clears it.
configIdentityProviderConfigYes
display_namestringYes
issuerstring—Upstream issuer; required for OIDC connections. May contain {tenant} for multi-tenant issuers. Cannot change while identities are linked.
jit_default_role_idstring—
jit_provisioningboolean—
linking_policystring—
verify_existing | trusted_verified_email | create_only
organization_idstring—
statestring—
active | disabled
trust_upstream_mfaboolean—
Complete request schema
{
  "additionalProperties": false,
  "properties": {
    "adapter": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_-]{0,31}$",
      "description": "Defaults to oidc. Built-in adapters (FED-002): oidc (generic OpenID Connect), github (OAuth 2.0 with the REST user API; numeric account ID as subject; only verified emails), google (fixed issuer https://accounts.google.com; allowed_tenants restricts to Workspace domains through the hd claim), microsoft (Entra ID work and school accounts: issuer https://login.microsoftonline.com/{tenant}/v2.0 selected by tid, allowed_tenants required; its email claim is never treated as verified, so trusted_verified_email linking is refused). Deployments can register further adapters in code; unknown names are refused."
    },
    "alias": {
      "type": "string",
      "description": "Lower-case letters, digits and dashes (2..63). Part of the registered callback URL; cannot be changed."
    },
    "claim_mapping": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/ClaimMapping"
        },
        {
          "type": "null"
        }
      ]
    },
    "client_secret": {
      "type": [
        "string",
        "null"
      ],
      "x-secret": true,
      "format": "password",
      "description": "Upstream client secret (write-only; stored encrypted and never returned, see has_client_secret). On PUT, omit to keep the current secret; an empty string clears it."
    },
    "config": {
      "$ref": "#/components/schemas/IdentityProviderConfig"
    },
    "display_name": {
      "type": "string",
      "maxLength": 100
    },
    "issuer": {
      "type": "string",
      "description": "Upstream issuer; required for OIDC connections. May contain {tenant} for multi-tenant issuers. Cannot change while identities are linked."
    },
    "jit_default_role_id": {
      "type": "string"
    },
    "jit_provisioning": {
      "type": "boolean"
    },
    "linking_policy": {
      "type": "string",
      "enum": [
        "verify_existing",
        "trusted_verified_email",
        "create_only"
      ]
    },
    "organization_id": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ]
    },
    "trust_upstream_mfa": {
      "type": "boolean"
    }
  },
  "type": "object",
  "required": [
    "alias",
    "config",
    "display_name"
  ]
}

Responses

200 OK

application/json

FieldTypeRequiredDescription
adapterstringYesThe provider adapter; saml for a SAML connection (FED-014).
aliasstringYes
claim_mappingClaimMappingYes
configIdentityProviderConfigYes
created_atstringYes
display_namestringYes
has_client_secretbooleanYes
idstringYes
issuerstringYes
jit_default_role_idstring—
jit_provisioningbooleanYes
kindstringYesoidc, oauth2_social or saml. SAML connections are listed here; PUT answers 409 for them (manage them under /saml/connections) and POST /identity-providers/{id}/test reports SAML certificate diagnostics without contacting the provider.
linking_policystringYes
mapping_revisionintegerYes
organization_idstring—
statestringYes
trust_upstream_mfabooleanYes
updated_atstringYes
versionintegerYes

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "ETag": {
    "$ref": "#/components/headers/ETag"
  }
}
400 Malformed request, invalid JSON (duplicate members, unknown fields, wrong types), invalid cursor or invalid transaction (code invalid_request, transaction_invalid, invalid_proof, invitation_invalid).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
412 If-Match does not match the current version (code precondition_failed).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
413 Body exceeds limits.max_body_bytes (code payload_too_large).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
415 Wrong Content-Type (code unsupported_media_type).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
422 Validation failed (code validation_failed, password_policy, idempotency_key_reused); errors maps fields to messages.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
428 If-Match header is required (code precondition_required).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
503 Load shedding, realm unavailable or dependency failure (code unavailable, upstream_unavailable). May include Retry-After.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  }
}

Operation replaceIdentityProvider · Schema definitions · OpenAPI contract

DELETE/api/v1/realms/{realm}/identity-providers/{id}+

Delete an identity provider connection

AuthenticationadminTokenTrust classadministrativePermissionsrealm.identity_providers.write

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
idpathYesResource identifier.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}

Responses

204 No Content

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
503 Load shedding, realm unavailable or dependency failure (code unavailable, upstream_unavailable). May include Retry-After.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  }
}

Operation deleteIdentityProvider · Schema definitions · OpenAPI contract

POST/api/v1/realms/{realm}/identity-providers/{id}/test+

Test a connection (redacted diagnostics)

Fetches discovery and keys through the egress policy without changing state. Any request body is ignored.

AuthenticationadminTokenTrust classadministrativePermissionsrealm.identity_providers.write

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
idpathYesResource identifier.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}
Idempotency-Keyheader—Actor/realm/route-bound idempotency key (API-005) for POST requests, at most 255 characters (422 otherwise), kept for 24 hours; only a digest of the key is stored. The request is identified by its method, exact path and body: a replay with the same path and body returns the stored status and response with Idempotent-Replayed: true; the same key with a different body or another path on the same route (another resource) returns 422 idempotency_key_reused; a request still in progress returns 409. Only successful responses are recorded: when the original request failed (an error or a status of 400 or above) the key is released and a retry runs again. Responses containing one-time secrets (members such as client_secret, token, api_key, access_token, refresh_token, id_token, recovery_codes, secret or webhook_secrets) are never stored or replayed (409 with original_status).
{"type":"string","maxLength":255}

Responses

200 OK

application/json

FieldTypeRequiredDescription
authorization_endpointstring—
issuerstringYes
jwks_uristring—
okbooleanYes
problemsarray,nullYes
signing_keysintegerYes
supports_pkce_s256booleanYes
token_endpointstring—

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Idempotent-Replayed": {
    "$ref": "#/components/headers/Idempotent-Replayed"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
422 Validation failed (code validation_failed, password_policy, idempotency_key_reused); errors maps fields to messages.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
503 Load shedding, realm unavailable or dependency failure (code unavailable, upstream_unavailable). May include Retry-After.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  }
}

Operation testIdentityProvider · Schema definitions · OpenAPI contract

GET/api/v1/realms/{realm}/users/{user}/linked-identities+

List a user's linked identities

AuthenticationadminTokenTrust classadministrativePermissionsrealm.users.read

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
userpathYesUser identifier.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}
cursorquery—Opaque cursor from a previous page (next_cursor). Cursors are HMAC-bound to the realm and listing.
{"type":"string"}
limitquery—Page size; defaults to limits.default_page_size and is capped at limits.max_page_size.
{"type":"integer","minimum":1}

Responses

200 OK

application/json

FieldTypeRequiredDescription
itemsarrayYes
next_cursorstring—Opaque cursor for the next page; empty on the last page (API-004).

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
503 Load shedding, realm unavailable or dependency failure (code unavailable, upstream_unavailable). May include Retry-After.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  }
}

Operation listUserLinkedIdentities · Schema definitions · OpenAPI contract

DELETE/api/v1/realms/{realm}/users/{user}/linked-identities/{id}+

Unlink a user's external identity

AuthenticationadminTokenTrust classadministrativePermissionsrealm.users.write

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
userpathYesUser identifier.
{"type":"string"}
idpathYesResource identifier.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}

Responses

204 No Content

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
503 Load shedding, realm unavailable or dependency failure (code unavailable, upstream_unavailable). May include Retry-After.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  }
}

Operation unlinkUserIdentity · Schema definitions · OpenAPI contract

GET/api/v1/realms/{realm}/organizations/{org}/identity-providers+

List the organization's connections

AuthenticationaccountToken or adminTokenTrust classuser-self-service-or-administrativePermissionsorg.identity_providers.write

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
orgpathYesOrganization identifier (a selector; access is checked, API-003).
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}
cursorquery—Opaque cursor from a previous page (next_cursor). Cursors are HMAC-bound to the realm and listing.
{"type":"string"}
limitquery—Page size; defaults to limits.default_page_size and is capped at limits.max_page_size.
{"type":"integer","minimum":1}

Responses

200 OK

application/json

FieldTypeRequiredDescription
itemsarray—
next_cursorstring—Opaque cursor for the next page; empty on the last page (API-004).

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
400 Malformed request, invalid JSON (duplicate members, unknown fields, wrong types), invalid cursor or invalid transaction (code invalid_request, transaction_invalid, invalid_proof, invitation_invalid).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
422 Validation failed (code validation_failed, password_policy, idempotency_key_reused); errors maps fields to messages.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

Operation listOrganizationIdentityProviders · Schema definitions · OpenAPI contract

POST/api/v1/realms/{realm}/organizations/{org}/identity-providers+

Create an organization connection

Organization-scoped federation connections managed by organization administrators (TEN-007). The connection is always scoped to the path organization; trusted-email linking is limited to the organization's verified domains; trust_upstream_mfa requires a realm administrator. Writes require an MFA session.

AuthenticationaccountToken or adminTokenTrust classuser-self-service-or-administrativePermissionsorg.identity_providers.write

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
orgpathYesOrganization identifier (a selector; access is checked, API-003).
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}

Request body

application/json · required

FieldTypeRequiredDescription
adapterstring—Defaults to oidc. Built-in adapters (FED-002): oidc (generic OpenID Connect), github (OAuth 2.0 with the REST user API; numeric account ID as subject; only verified emails), google (fixed issuer https://accounts.google.com; allowed_tenants restricts to Workspace domains through the hd claim), microsoft (Entra ID work and school accounts: issuer https://login.microsoftonline.com/{tenant}/v2.0 selected by tid, allowed_tenants required; its email claim is never treated as verified, so trusted_verified_email linking is refused). Deployments can register further adapters in code; unknown names are refused.
aliasstringYesLower-case letters, digits and dashes (2..63). Part of the registered callback URL; cannot be changed.
claim_mappingoneOf—
client_secretone-time secretstring,null—Upstream client secret (write-only; stored encrypted and never returned, see has_client_secret). On PUT, omit to keep the current secret; an empty string clears it.
configIdentityProviderConfigYes
display_namestringYes
issuerstring—Upstream issuer; required for OIDC connections. May contain {tenant} for multi-tenant issuers. Cannot change while identities are linked.
jit_default_role_idstring—
jit_provisioningboolean—
linking_policystring—
verify_existing | trusted_verified_email | create_only
organization_idstring—
statestring—
active | disabled
trust_upstream_mfaboolean—
Complete request schema
{
  "additionalProperties": false,
  "properties": {
    "adapter": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_-]{0,31}$",
      "description": "Defaults to oidc. Built-in adapters (FED-002): oidc (generic OpenID Connect), github (OAuth 2.0 with the REST user API; numeric account ID as subject; only verified emails), google (fixed issuer https://accounts.google.com; allowed_tenants restricts to Workspace domains through the hd claim), microsoft (Entra ID work and school accounts: issuer https://login.microsoftonline.com/{tenant}/v2.0 selected by tid, allowed_tenants required; its email claim is never treated as verified, so trusted_verified_email linking is refused). Deployments can register further adapters in code; unknown names are refused."
    },
    "alias": {
      "type": "string",
      "description": "Lower-case letters, digits and dashes (2..63). Part of the registered callback URL; cannot be changed."
    },
    "claim_mapping": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/ClaimMapping"
        },
        {
          "type": "null"
        }
      ]
    },
    "client_secret": {
      "type": [
        "string",
        "null"
      ],
      "x-secret": true,
      "format": "password",
      "description": "Upstream client secret (write-only; stored encrypted and never returned, see has_client_secret). On PUT, omit to keep the current secret; an empty string clears it."
    },
    "config": {
      "$ref": "#/components/schemas/IdentityProviderConfig"
    },
    "display_name": {
      "type": "string",
      "maxLength": 100
    },
    "issuer": {
      "type": "string",
      "description": "Upstream issuer; required for OIDC connections. May contain {tenant} for multi-tenant issuers. Cannot change while identities are linked."
    },
    "jit_default_role_id": {
      "type": "string"
    },
    "jit_provisioning": {
      "type": "boolean"
    },
    "linking_policy": {
      "type": "string",
      "enum": [
        "verify_existing",
        "trusted_verified_email",
        "create_only"
      ]
    },
    "organization_id": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ]
    },
    "trust_upstream_mfa": {
      "type": "boolean"
    }
  },
  "type": "object",
  "required": [
    "alias",
    "config",
    "display_name"
  ]
}

Responses

201 OK

application/json

FieldTypeRequiredDescription
adapterstringYesThe provider adapter; saml for a SAML connection (FED-014).
aliasstringYes
claim_mappingClaimMappingYes
configIdentityProviderConfigYes
created_atstringYes
display_namestringYes
has_client_secretbooleanYes
idstringYes
issuerstringYes
jit_default_role_idstring—
jit_provisioningbooleanYes
kindstringYesoidc, oauth2_social or saml. SAML connections are listed here; PUT answers 409 for them (manage them under /saml/connections) and POST /identity-providers/{id}/test reports SAML certificate diagnostics without contacting the provider.
linking_policystringYes
mapping_revisionintegerYes
organization_idstring—
statestringYes
trust_upstream_mfabooleanYes
updated_atstringYes
versionintegerYes

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
400 Malformed request, invalid JSON (duplicate members, unknown fields, wrong types), invalid cursor or invalid transaction (code invalid_request, transaction_invalid, invalid_proof, invitation_invalid).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
422 Validation failed (code validation_failed, password_policy, idempotency_key_reused); errors maps fields to messages.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

Operation createOrganizationIdentityProvider · Schema definitions · OpenAPI contract

GET/api/v1/realms/{realm}/organizations/{org}/identity-providers/{id}+

Get an organization connection

AuthenticationaccountToken or adminTokenTrust classuser-self-service-or-administrativePermissionsorg.identity_providers.write

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
orgpathYesOrganization identifier (a selector; access is checked, API-003).
{"type":"string"}
idpathYesResource identifier.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}

Responses

200 OK

application/json

FieldTypeRequiredDescription
adapterstringYesThe provider adapter; saml for a SAML connection (FED-014).
aliasstringYes
claim_mappingClaimMappingYes
configIdentityProviderConfigYes
created_atstringYes
display_namestringYes
has_client_secretbooleanYes
idstringYes
issuerstringYes
jit_default_role_idstring—
jit_provisioningbooleanYes
kindstringYesoidc, oauth2_social or saml. SAML connections are listed here; PUT answers 409 for them (manage them under /saml/connections) and POST /identity-providers/{id}/test reports SAML certificate diagnostics without contacting the provider.
linking_policystringYes
mapping_revisionintegerYes
organization_idstring—
statestringYes
trust_upstream_mfabooleanYes
updated_atstringYes
versionintegerYes

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
400 Malformed request, invalid JSON (duplicate members, unknown fields, wrong types), invalid cursor or invalid transaction (code invalid_request, transaction_invalid, invalid_proof, invitation_invalid).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
422 Validation failed (code validation_failed, password_policy, idempotency_key_reused); errors maps fields to messages.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

Operation getOrganizationIdentityProvider · Schema definitions · OpenAPI contract

PUT/api/v1/realms/{realm}/organizations/{org}/identity-providers/{id}+

Update an organization connection

Organization-scoped federation connections managed by organization administrators (TEN-007). The connection is always scoped to the path organization; trusted-email linking is limited to the organization's verified domains; trust_upstream_mfa requires a realm administrator. Writes require an MFA session.

AuthenticationaccountToken or adminTokenTrust classuser-self-service-or-administrativePermissionsorg.identity_providers.write

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
orgpathYesOrganization identifier (a selector; access is checked, API-003).
{"type":"string"}
idpathYesResource identifier.
{"type":"string"}
If-MatchheaderYesExpected resource version from the ETag. Required: missing returns 428, stale returns 412.
{"type":"string","examples":["W/\"v12\""]}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}

Request body

application/json · required

FieldTypeRequiredDescription
adapterstring—Defaults to oidc. Built-in adapters (FED-002): oidc (generic OpenID Connect), github (OAuth 2.0 with the REST user API; numeric account ID as subject; only verified emails), google (fixed issuer https://accounts.google.com; allowed_tenants restricts to Workspace domains through the hd claim), microsoft (Entra ID work and school accounts: issuer https://login.microsoftonline.com/{tenant}/v2.0 selected by tid, allowed_tenants required; its email claim is never treated as verified, so trusted_verified_email linking is refused). Deployments can register further adapters in code; unknown names are refused.
aliasstringYesLower-case letters, digits and dashes (2..63). Part of the registered callback URL; cannot be changed.
claim_mappingoneOf—
client_secretone-time secretstring,null—Upstream client secret (write-only; stored encrypted and never returned, see has_client_secret). On PUT, omit to keep the current secret; an empty string clears it.
configIdentityProviderConfigYes
display_namestringYes
issuerstring—Upstream issuer; required for OIDC connections. May contain {tenant} for multi-tenant issuers. Cannot change while identities are linked.
jit_default_role_idstring—
jit_provisioningboolean—
linking_policystring—
verify_existing | trusted_verified_email | create_only
organization_idstring—
statestring—
active | disabled
trust_upstream_mfaboolean—
Complete request schema
{
  "additionalProperties": false,
  "properties": {
    "adapter": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_-]{0,31}$",
      "description": "Defaults to oidc. Built-in adapters (FED-002): oidc (generic OpenID Connect), github (OAuth 2.0 with the REST user API; numeric account ID as subject; only verified emails), google (fixed issuer https://accounts.google.com; allowed_tenants restricts to Workspace domains through the hd claim), microsoft (Entra ID work and school accounts: issuer https://login.microsoftonline.com/{tenant}/v2.0 selected by tid, allowed_tenants required; its email claim is never treated as verified, so trusted_verified_email linking is refused). Deployments can register further adapters in code; unknown names are refused."
    },
    "alias": {
      "type": "string",
      "description": "Lower-case letters, digits and dashes (2..63). Part of the registered callback URL; cannot be changed."
    },
    "claim_mapping": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/ClaimMapping"
        },
        {
          "type": "null"
        }
      ]
    },
    "client_secret": {
      "type": [
        "string",
        "null"
      ],
      "x-secret": true,
      "format": "password",
      "description": "Upstream client secret (write-only; stored encrypted and never returned, see has_client_secret). On PUT, omit to keep the current secret; an empty string clears it."
    },
    "config": {
      "$ref": "#/components/schemas/IdentityProviderConfig"
    },
    "display_name": {
      "type": "string",
      "maxLength": 100
    },
    "issuer": {
      "type": "string",
      "description": "Upstream issuer; required for OIDC connections. May contain {tenant} for multi-tenant issuers. Cannot change while identities are linked."
    },
    "jit_default_role_id": {
      "type": "string"
    },
    "jit_provisioning": {
      "type": "boolean"
    },
    "linking_policy": {
      "type": "string",
      "enum": [
        "verify_existing",
        "trusted_verified_email",
        "create_only"
      ]
    },
    "organization_id": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ]
    },
    "trust_upstream_mfa": {
      "type": "boolean"
    }
  },
  "type": "object",
  "required": [
    "alias",
    "config",
    "display_name"
  ]
}

Responses

200 OK

application/json

FieldTypeRequiredDescription
adapterstringYesThe provider adapter; saml for a SAML connection (FED-014).
aliasstringYes
claim_mappingClaimMappingYes
configIdentityProviderConfigYes
created_atstringYes
display_namestringYes
has_client_secretbooleanYes
idstringYes
issuerstringYes
jit_default_role_idstring—
jit_provisioningbooleanYes
kindstringYesoidc, oauth2_social or saml. SAML connections are listed here; PUT answers 409 for them (manage them under /saml/connections) and POST /identity-providers/{id}/test reports SAML certificate diagnostics without contacting the provider.
linking_policystringYes
mapping_revisionintegerYes
organization_idstring—
statestringYes
trust_upstream_mfabooleanYes
updated_atstringYes
versionintegerYes

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
400 Malformed request, invalid JSON (duplicate members, unknown fields, wrong types), invalid cursor or invalid transaction (code invalid_request, transaction_invalid, invalid_proof, invitation_invalid).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
412 If-Match does not match the current version (code precondition_failed).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
422 Validation failed (code validation_failed, password_policy, idempotency_key_reused); errors maps fields to messages.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
428 If-Match header is required (code precondition_required).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

Operation updateOrganizationIdentityProvider · Schema definitions · OpenAPI contract

DELETE/api/v1/realms/{realm}/organizations/{org}/identity-providers/{id}+

Delete an organization connection

AuthenticationaccountToken or adminTokenTrust classuser-self-service-or-administrativePermissionsorg.identity_providers.write

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
orgpathYesOrganization identifier (a selector; access is checked, API-003).
{"type":"string"}
idpathYesResource identifier.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}

Responses

204 No Content

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
400 Malformed request, invalid JSON (duplicate members, unknown fields, wrong types), invalid cursor or invalid transaction (code invalid_request, transaction_invalid, invalid_proof, invitation_invalid).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
422 Validation failed (code validation_failed, password_policy, idempotency_key_reused); errors maps fields to messages.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

Operation deleteOrganizationIdentityProvider · Schema definitions · OpenAPI contract

GET/api/v1/realms/{realm}/federation-transfers+

List federation transfers

FED-016.

AuthenticationadminTokenTrust classadministrativePermissionsrealm.identity_providers.read

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}

Responses

200 OK

application/json

FieldTypeRequiredDescription
itemsarrayYes
next_cursorstring—

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
400 Malformed request, invalid JSON (duplicate members, unknown fields, wrong types), invalid cursor or invalid transaction (code invalid_request, transaction_invalid, invalid_proof, invitation_invalid).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
422 Validation failed (code validation_failed, password_policy, idempotency_key_reused); errors maps fields to messages.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

Operation listFederationTransfers · Schema definitions · OpenAPI contract

POST/api/v1/realms/{realm}/federation-transfers+

Plan a federation transfer

FED-016. Moves account links from one provider connection to another (same organization scope) by a migration map: map takes explicit entries (more can be added to the draft, up to 50000); same_subject maps every source link to the same subject at the target. The plan is analysed at once (summary by outcome). Accounts are never relinked by email.

AuthenticationadminTokenTrust classadministrativePermissionsrealm.identity_providers.write

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}

Request body

application/json · required

FieldTypeRequiredDescription
source_provider_idstringYes
target_provider_idstringYes
modestringYes
map | same_subject
target_tenantstring—
reasonstringYes
entriesarray—
Complete request schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "source_provider_id",
    "target_provider_id",
    "mode",
    "reason"
  ],
  "properties": {
    "source_provider_id": {
      "type": "string"
    },
    "target_provider_id": {
      "type": "string"
    },
    "mode": {
      "type": "string",
      "enum": [
        "map",
        "same_subject"
      ]
    },
    "target_tenant": {
      "type": "string"
    },
    "reason": {
      "type": "string",
      "maxLength": 500
    },
    "entries": {
      "type": "array",
      "maxItems": 2000,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "source_subject",
          "target_subject"
        ],
        "properties": {
          "source_subject": {
            "type": "string",
            "maxLength": 255
          },
          "source_issuer": {
            "type": "string",
            "description": "Needed when the subject is linked under several source issuers (multi-tenant source)."
          },
          "target_subject": {
            "type": "string",
            "maxLength": 255
          },
          "target_tenant": {
            "type": "string",
            "description": "Tenant substituted into a multi-tenant target issuer."
          }
        }
      }
    }
  }
}

Responses

201 OK

application/json

FieldTypeRequiredDescription
idstringYes
source_provider_idstringYes
target_provider_idstringYes
modestringYes
map | same_subject
target_tenantstring—
statestringYes
draft | approved | applied | cancelled
reasonstringYes
summaryobjectYesEntry count by outcome, plus total.
created_by_idstringYes
approved_by_idstring—
applied_by_idstring—
created_atstringYes
approved_atstring—
applied_atstring—
versionintegerYes

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
400 Malformed request, invalid JSON (duplicate members, unknown fields, wrong types), invalid cursor or invalid transaction (code invalid_request, transaction_invalid, invalid_proof, invitation_invalid).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
422 Validation failed (code validation_failed, password_policy, idempotency_key_reused); errors maps fields to messages.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

Operation createFederationTransfer · Schema definitions · OpenAPI contract

GET/api/v1/realms/{realm}/federation-transfers/{id}+

Get a federation transfer

AuthenticationadminTokenTrust classadministrativePermissionsrealm.identity_providers.read

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
idpathYesResource identifier.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}

Responses

200 OK

application/json

FieldTypeRequiredDescription
idstringYes
source_provider_idstringYes
target_provider_idstringYes
modestringYes
map | same_subject
target_tenantstring—
statestringYes
draft | approved | applied | cancelled
reasonstringYes
summaryobjectYesEntry count by outcome, plus total.
created_by_idstringYes
approved_by_idstring—
applied_by_idstring—
created_atstringYes
approved_atstring—
applied_atstring—
versionintegerYes

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
400 Malformed request, invalid JSON (duplicate members, unknown fields, wrong types), invalid cursor or invalid transaction (code invalid_request, transaction_invalid, invalid_proof, invitation_invalid).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
422 Validation failed (code validation_failed, password_policy, idempotency_key_reused); errors maps fields to messages.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

Operation getFederationTransfer · Schema definitions · OpenAPI contract

GET/api/v1/realms/{realm}/federation-transfers/{id}/entries+

List transfer entries and their outcomes

FED-016. Query outcome filters by outcome; after (the last seq seen) and limit page through entries.

AuthenticationadminTokenTrust classadministrativePermissionsrealm.identity_providers.read

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
idpathYesResource identifier.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}

Responses

200 OK

application/json

FieldTypeRequiredDescription
itemsarrayYes
next_afterinteger—

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
400 Malformed request, invalid JSON (duplicate members, unknown fields, wrong types), invalid cursor or invalid transaction (code invalid_request, transaction_invalid, invalid_proof, invitation_invalid).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
422 Validation failed (code validation_failed, password_policy, idempotency_key_reused); errors maps fields to messages.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

Operation listFederationTransferEntries · Schema definitions · OpenAPI contract

POST/api/v1/realms/{realm}/federation-transfers/{id}/entries+

Add map entries to a draft

FED-016. Only for draft map transfers; the plan is analysed again.

AuthenticationadminTokenTrust classadministrativePermissionsrealm.identity_providers.write

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
idpathYesResource identifier.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}

Request body

application/json · required

FieldTypeRequiredDescription
entriesarrayYes
Complete request schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "entries"
  ],
  "properties": {
    "entries": {
      "type": "array",
      "minItems": 1,
      "maxItems": 2000,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "source_subject",
          "target_subject"
        ],
        "properties": {
          "source_subject": {
            "type": "string",
            "maxLength": 255
          },
          "source_issuer": {
            "type": "string",
            "description": "Needed when the subject is linked under several source issuers (multi-tenant source)."
          },
          "target_subject": {
            "type": "string",
            "maxLength": 255
          },
          "target_tenant": {
            "type": "string",
            "description": "Tenant substituted into a multi-tenant target issuer."
          }
        }
      }
    }
  }
}

Responses

200 OK

application/json

FieldTypeRequiredDescription
idstringYes
source_provider_idstringYes
target_provider_idstringYes
modestringYes
map | same_subject
target_tenantstring—
statestringYes
draft | approved | applied | cancelled
reasonstringYes
summaryobjectYesEntry count by outcome, plus total.
created_by_idstringYes
approved_by_idstring—
applied_by_idstring—
created_atstringYes
approved_atstring—
applied_atstring—
versionintegerYes

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
400 Malformed request, invalid JSON (duplicate members, unknown fields, wrong types), invalid cursor or invalid transaction (code invalid_request, transaction_invalid, invalid_proof, invitation_invalid).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
422 Validation failed (code validation_failed, password_policy, idempotency_key_reused); errors maps fields to messages.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

Operation addFederationTransferEntries · Schema definitions · OpenAPI contract

POST/api/v1/realms/{realm}/federation-transfers/{id}/approve+

Approve a federation transfer

FED-016. By an administrator other than the author (403 otherwise). The plan is analysed again; 409 when nothing could be applied.

AuthenticationadminTokenTrust classadministrativePermissionsrealm.identity_providers.write

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
idpathYesResource identifier.
{"type":"string"}
If-Matchheader—Expected resource version from the ETag (W/"v12" or "v12"). Stale versions return 412.
{"type":"string","examples":["W/\"v12\""]}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}

Responses

200 OK

application/json

FieldTypeRequiredDescription
idstringYes
source_provider_idstringYes
target_provider_idstringYes
modestringYes
map | same_subject
target_tenantstring—
statestringYes
draft | approved | applied | cancelled
reasonstringYes
summaryobjectYesEntry count by outcome, plus total.
created_by_idstringYes
approved_by_idstring—
applied_by_idstring—
created_atstringYes
approved_atstring—
applied_atstring—
versionintegerYes

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
400 Malformed request, invalid JSON (duplicate members, unknown fields, wrong types), invalid cursor or invalid transaction (code invalid_request, transaction_invalid, invalid_proof, invitation_invalid).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
422 Validation failed (code validation_failed, password_policy, idempotency_key_reused); errors maps fields to messages.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

Operation approveFederationTransfer · Schema definitions · OpenAPI contract

POST/api/v1/realms/{realm}/federation-transfers/{id}/apply+

Apply an approved federation transfer

FED-016. Analyses again under lock and moves only entries still ready (the link keeps its ID and account; tokens kept for the old connection are discarded); entries already linked at the target drop their source link. Collisions and duplicates are skipped and stay in the report. Applies once.

AuthenticationadminTokenTrust classadministrativePermissionsrealm.identity_providers.write

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
idpathYesResource identifier.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}

Responses

200 OK

application/json

FieldTypeRequiredDescription
idstringYes
source_provider_idstringYes
target_provider_idstringYes
modestringYes
map | same_subject
target_tenantstring—
statestringYes
draft | approved | applied | cancelled
reasonstringYes
summaryobjectYesEntry count by outcome, plus total.
created_by_idstringYes
approved_by_idstring—
applied_by_idstring—
created_atstringYes
approved_atstring—
applied_atstring—
versionintegerYes

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
400 Malformed request, invalid JSON (duplicate members, unknown fields, wrong types), invalid cursor or invalid transaction (code invalid_request, transaction_invalid, invalid_proof, invitation_invalid).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
422 Validation failed (code validation_failed, password_policy, idempotency_key_reused); errors maps fields to messages.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

Operation applyFederationTransfer · Schema definitions · OpenAPI contract

POST/api/v1/realms/{realm}/federation-transfers/{id}/cancel+

Cancel a federation transfer

AuthenticationadminTokenTrust classadministrativePermissionsrealm.identity_providers.write

Parameters

NameLocationRequiredDetails
realmpathYesRealm name (path-based issuer). Unknown realms return 404.
{"type":"string"}
idpathYesResource identifier.
{"type":"string"}
X-Request-Idheader—Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in X-Request-Id and problem request_id.
{"type":"string","maxLength":64,"pattern":"^[\\x21-\\x7e]+$"}

Responses

204 No Content

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
400 Malformed request, invalid JSON (duplicate members, unknown fields, wrong types), invalid cursor or invalid transaction (code invalid_request, transaction_invalid, invalid_proof, invitation_invalid).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
401 Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}
403 Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required, grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted). Step-up problems carry obligations.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
404 Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
409 Conflicts with current state, or an idempotent request with the same key is still in progress / carried a one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
422 Validation failed (code validation_failed, password_policy, idempotency_key_reused); errors maps fields to messages.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}
500 Unexpected error (code internal_error); no stack traces or secrets.

application/problem+json

FieldTypeRequiredDescription
typestringYeshttps://auth.proudbase.com/problems/{code}
titlestringYes
statusintegerYes
codestringYesStable machine-readable error code.
invalid_request | validation_failed | unauthenticated | forbidden | not_found | conflict | precondition_failed | precondition_required | rate_limited | unavailable | internal_error | payload_too_large | unsupported_media_type | step_up_required | recent_authentication_required | mfa_required | recovery_restricted | transaction_invalid | transaction_expired | invalid_credentials | invalid_proof | unexpected_step | password_policy | last_owner | grant_ceiling_exceeded | impersonation_denied | impersonation_restricted | feature_disabled | invitation_invalid | last_sign_in_method | idempotency_key_reused | account_unavailable | sso_required | upstream_unavailable
detailstring—Client-safe detail; never contains secrets.
errorsobject—Field name -> validation message.
request_idstring—Correlation identifier, equal to the X-Request-Id response header.
obligationsarray—Present on step-up / recent-authentication / MFA problems.
original_statusinteger—Present when an idempotent replay is refused because the original response carried a one-time secret.

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

Operation cancelFederationTransfer · Schema definitions · OpenAPI contract

ProudAuth · Self-hosted identityBuilt 2026-10-13 · d9cc813ae809 · content snapshot
⌕

Search all guides and the API contract.

↑ ↓ to navigate Enter to open · Esc to close