Webhooks

Webhook subscriptions and deliveries (event schemas in api/events). 10 operations

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

GET/api/v1/realms/{realm}/webhooks+

List webhook subscriptions

AuthenticationadminTokenTrust classadministrativePermissionsrealm.webhooks.read

Parameters

Name	Location	Required	Details
`realm`	path	Yes	Realm name (path-based issuer). Unknown realms return 404. `{"type":"string"}`
`X-Request-Id`	header	—	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]+$"}`
`organization_id`	query	—	Filter by organization. `{"type":"string"}`

Responses

200 OK

application/json

Field	Type	Required	Description
`items`	array	Yes
`event_types`	array	—	Subscribable event types.

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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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 listWebhooks · Schema definitions · OpenAPI contract

POST/api/v1/realms/{realm}/webhooks+

Create a webhook subscription

AuthenticationadminTokenTrust classadministrativePermissionsrealm.webhooks.write

Parameters

Name	Location	Required	Details
`realm`	path	Yes	Realm name (path-based issuer). Unknown realms return 404. `{"type":"string"}`
`X-Request-Id`	header	—	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-Key`	header	—	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

Field	Type	Required	Description
`allow_private_network`	boolean	—
`destination_url`	string	Yes	HTTPS destination subject to the operator egress policy.
`event_types`	array,null	Yes	Event types from the catalog in api/events (also returned by GET /webhooks as event_types).
`name`	string	Yes
`organization_id`	string	—
`payload_form`	string	—	`minimal \| standard`
`event_version`	integer	—	Event schema version deliveries are rendered to (EXT-018); default 1. See api/events/README.md. `1 \| 2`

Complete request schema

{
  "additionalProperties": false,
  "properties": {
    "allow_private_network": {
      "type": "boolean"
    },
    "destination_url": {
      "type": "string",
      "format": "uri",
      "description": "HTTPS destination subject to the operator egress policy."
    },
    "event_types": {
      "items": {
        "type": "string"
      },
      "type": [
        "array",
        "null"
      ],
      "minItems": 1,
      "description": "Event types from the catalog in api/events (also returned by GET /webhooks as event_types)."
    },
    "name": {
      "type": "string"
    },
    "organization_id": {
      "type": "string"
    },
    "payload_form": {
      "type": "string",
      "enum": [
        "minimal",
        "standard"
      ]
    },
    "event_version": {
      "type": "integer",
      "enum": [
        1,
        2
      ],
      "description": "Event schema version deliveries are rendered to (EXT-018); default 1. See api/events/README.md."
    }
  },
  "type": "object",
  "required": [
    "destination_url",
    "event_types",
    "name"
  ]
}

Responses

201 Created

application/json

Field	Type	Required	Description
`subscription`	WebhookSubscription	Yes
`signing_secret`one-time secret	string	Yes	Webhook signing secret. Returned exactly once; it is never stored in plaintext, never shown again and never replayed from the idempotency store.
`notice`	string	Yes

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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"
  }
}

application/problem+json

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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 createWebhook · Schema definitions · OpenAPI contract

GET/api/v1/realms/{realm}/webhooks/{id}+

Get a webhook subscription

AuthenticationadminTokenTrust classadministrativePermissionsrealm.webhooks.read

Parameters

Name	Location	Required	Details
`realm`	path	Yes	Realm name (path-based issuer). Unknown realms return 404. `{"type":"string"}`
`id`	path	Yes	Resource identifier. `{"type":"string"}`
`X-Request-Id`	header	—	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

Field	Type	Required	Description
`allow_private_network`	boolean	Yes
`created_at`	string	Yes
`destination_url`	string	Yes
`event_types`	array,null	Yes
`id`	string	Yes
`name`	string	Yes
`organization_id`	string	—
`owner_user_id`	string	—
`payload_form`	string	Yes
`state`	string	Yes	`active \| paused \| disabled`
`version`	integer	Yes
`event_version`	integer	Yes	Event schema version of deliveries (EXT-018).
`plugin_id`	string	—	Set when a plugin manages the subscription; PATCH and DELETE then return 409 (EXT-014).

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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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"
  }
}

application/problem+json

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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 getWebhook · Schema definitions · OpenAPI contract

PATCH/api/v1/realms/{realm}/webhooks/{id}+

Update a webhook subscription

Partial update: absent fields keep their current values. A state-only change (pause, resume, disable) does not re-resolve the destination. The organization of a subscription cannot change.

AuthenticationadminTokenTrust classadministrativePermissionsrealm.webhooks.write

Parameters

Name	Location	Required	Details
`realm`	path	Yes	Realm name (path-based issuer). Unknown realms return 404. `{"type":"string"}`
`id`	path	Yes	Resource identifier. `{"type":"string"}`
`X-Request-Id`	header	—	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-Match`	header	—	Expected resource version from the ETag (W/"v12" or "v12"). Stale versions return 412. `{"type":"string","examples":["W/\"v12\""]}`

Request body

application/json · required

Field	Type	Required	Description
`allow_private_network`	boolean	—
`destination_url`	string	—	HTTPS destination subject to the operator egress policy.
`event_types`	array,null	—	Event types from the catalog in api/events (also returned by GET /webhooks as event_types).
`name`	string	—
`event_version`	integer	—	Event schema version (EXT-018). `1 \| 2`
`payload_form`	string	—	`minimal \| standard`
`state`	string	—	`active \| paused \| disabled`

Complete request schema

{
  "additionalProperties": false,
  "properties": {
    "allow_private_network": {
      "type": "boolean"
    },
    "destination_url": {
      "type": "string",
      "format": "uri",
      "description": "HTTPS destination subject to the operator egress policy."
    },
    "event_types": {
      "items": {
        "type": "string"
      },
      "type": [
        "array",
        "null"
      ],
      "minItems": 1,
      "description": "Event types from the catalog in api/events (also returned by GET /webhooks as event_types)."
    },
    "name": {
      "type": "string"
    },
    "event_version": {
      "type": "integer",
      "enum": [
        1,
        2
      ],
      "description": "Event schema version (EXT-018)."
    },
    "payload_form": {
      "type": "string",
      "enum": [
        "minimal",
        "standard"
      ]
    },
    "state": {
      "type": "string",
      "enum": [
        "active",
        "paused",
        "disabled"
      ]
    }
  },
  "type": "object"
}

Responses

200 OK

application/json

Field	Type	Required	Description
`allow_private_network`	boolean	Yes
`created_at`	string	Yes
`destination_url`	string	Yes
`event_types`	array,null	Yes
`id`	string	Yes
`name`	string	Yes
`organization_id`	string	—
`owner_user_id`	string	—
`payload_form`	string	Yes
`state`	string	Yes	`active \| paused \| disabled`
`version`	integer	Yes
`event_version`	integer	Yes	Event schema version of deliveries (EXT-018).
`plugin_id`	string	—	Set when a plugin manages the subscription; PATCH and DELETE then return 409 (EXT-014).

Response headers

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

application/problem+json

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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"
  }
}

application/problem+json

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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 updateWebhook · Schema definitions · OpenAPI contract

DELETE/api/v1/realms/{realm}/webhooks/{id}+

Delete a webhook subscription

AuthenticationadminTokenTrust classadministrativePermissionsrealm.webhooks.write

Parameters

Name	Location	Required	Details
`realm`	path	Yes	Realm name (path-based issuer). Unknown realms return 404. `{"type":"string"}`
`id`	path	Yes	Resource identifier. `{"type":"string"}`
`X-Request-Id`	header	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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"
  }
}

application/problem+json

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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 deleteWebhook · Schema definitions · OpenAPI contract

POST/api/v1/realms/{realm}/webhooks/{id}/rotate-secret+

Rotate the signing secret

The previous secret remains valid (dual signatures) for 24 hours. Any request body is ignored.

AuthenticationadminTokenTrust classadministrativePermissionsrealm.webhooks.write

Parameters

Name	Location	Required	Details
`realm`	path	Yes	Realm name (path-based issuer). Unknown realms return 404. `{"type":"string"}`
`id`	path	Yes	Resource identifier. `{"type":"string"}`
`X-Request-Id`	header	—	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-Key`	header	—	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

Field	Type	Required	Description
`signing_secret`one-time secret	string	Yes	New webhook signing secret. Returned exactly once; it is never stored in plaintext, never shown again and never replayed from the idempotency store.
`previous_secret_valid_for_seconds`	integer	Yes

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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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"
  }
}

application/problem+json

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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 rotateWebhookSecret · Schema definitions · OpenAPI contract

GET/api/v1/realms/{realm}/webhooks/{id}/deliveries+

Delivery history

AuthenticationadminTokenTrust classadministrativePermissionsrealm.webhooks.read

Parameters

Name	Location	Required	Details
`realm`	path	Yes	Realm name (path-based issuer). Unknown realms return 404. `{"type":"string"}`
`id`	path	Yes	Resource identifier. `{"type":"string"}`
`X-Request-Id`	header	—	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]+$"}`
`cursor`	query	—	Opaque cursor from a previous page (next_cursor). Cursors are HMAC-bound to the realm and listing. `{"type":"string"}`
`limit`	query	—	Page size; defaults to limits.default_page_size and is capped at limits.max_page_size. `{"type":"integer","minimum":1}`
`limit`	query	—	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

Field	Type	Required	Description
`items`	array	Yes
`next_cursor`	string	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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"
  }
}

application/problem+json

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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 listWebhookDeliveries · Schema definitions · OpenAPI contract

POST/api/v1/realms/{realm}/webhooks/{id}/deliveries/{delivery}/replay+

Retry a delivery

Redelivers with the stable original event ID. Any request body is ignored.

AuthenticationadminTokenTrust classadministrativePermissionsrealm.webhooks.write

Parameters

Name	Location	Required	Details
`realm`	path	Yes	Realm name (path-based issuer). Unknown realms return 404. `{"type":"string"}`
`id`	path	Yes	Resource identifier. `{"type":"string"}`
`delivery`	path	Yes	Webhook delivery identifier. `{"type":"string"}`
`X-Request-Id`	header	—	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-Key`	header	—	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

202 Accepted

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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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"
  }
}

application/problem+json

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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 replayWebhookDelivery · Schema definitions · OpenAPI contract

GET/api/v1/realms/{realm}/webhooks/{id}/backlog+

Read a subscription's delivery backlog

Per-destination backlog (EXT-005): deliveries by state, the age of the oldest due delivery, the last successful delivery and the last failure category.

AuthenticationadminTokenTrust classadministrativePermissionsrealm.webhooks.read

Parameters

Name	Location	Required	Details
`realm`	path	Yes	Realm name (path-based issuer). Unknown realms return 404. `{"type":"string"}`
`id`	path	Yes	Resource identifier. `{"type":"string"}`
`X-Request-Id`	header	—	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

Field	Type	Required
`pending`	integer	—
`retrying`	integer	—
`dead_letter`	integer	—
`delivered`	integer	—
`oldest_due_seconds`	integer	—
`last_delivered_at`	string	—
`last_failure_category`	string	—

Response headers

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

application/problem+json

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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"
  }
}

application/problem+json

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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 getWebhookBacklog · Schema definitions · OpenAPI contract

POST/api/v1/realms/{realm}/webhooks/{id}/ownership-transfer+

Change the accountable owner of a webhook subscription

DOM-009: sets owner_user_id (an active or recovery_restricted account of the realm) of a webhook subscription, also when it has none or its owner left; a plugin-managed part keeps its plugin (plugin_id). Audited as webhook.ownership_transferred (metadata previous_owner_user_id, owner_user_id); the version moves. Honors If-Match.

AuthenticationadminTokenTrust classadministrativePermissionsrealm.webhooks.write

Parameters

Name	Location	Required	Details
`realm`	path	Yes	Realm name (path-based issuer). Unknown realms return 404. `{"type":"string"}`
`id`	path	Yes	Resource identifier. `{"type":"string"}`
`If-Match`	header	—	Expected resource version from the ETag (W/"v12" or "v12"). Stale versions return 412. `{"type":"string","examples":["W/\"v12\""]}`
`X-Request-Id`	header	—	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

Field	Type	Required	Description
`owner_user_id`	string	Yes

Complete request schema

{
  "type": "object",
  "properties": {
    "owner_user_id": {
      "type": "string"
    }
  },
  "required": [
    "owner_user_id"
  ],
  "additionalProperties": false
}

Responses

200 OK

application/json

Field	Type	Required	Description
`kind`	string	—	`webhook`
`id`	string	—
`owner_user_id`	string	—
`previous_owner_user_id`	string	—	Empty when it had no owner.
`version`	integer	—

Response headers

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

application/problem+json

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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"
  }
}

application/problem+json

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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

Field	Type	Required	Description
`type`	string	Yes	https://auth.proudbase.com/problems/{code}
`title`	string	Yes
`status`	integer	Yes
`code`	string	Yes	Stable 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
`detail`	string	—	Client-safe detail; never contains secrets.
`errors`	object	—	Field name -> validation message.
`request_id`	string	—	Correlation identifier, equal to the X-Request-Id response header.
`obligations`	array	—	Present on step-up / recent-authentication / MFA problems.
`original_status`	integer	—	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 transferWebhookOwnership · Schema definitions · OpenAPI contract