OAuth

OAuth 2.0 protocol endpoints (authorize, token, introspect, revoke, device authorization, PAR). Errors use the OAuth JSON format, not problem details. 11 operations

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

GET/realms/{realm}/oauth/authorize+

Authorization request (query)

Starts an authorization-code flow (PKCE S256 required). On success redirects (302) to the login UI or back to the client with code, state and iss. Errors that cannot be safely redirected are returned as OAuth JSON errors with status 400. May set pa_tx and pa_sid cookies.

AuthenticationPublic / endpoint-specific credentialsTrust classpublic-protocol-initiationPermissionsSee operation description

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]+$"}`
`response_type`	query	—	response_type `{"type":"string","const":"code"}`
`client_id`	query	—	client_id `{"type":"string"}`
`redirect_uri`	query	—	redirect_uri `{"type":"string","format":"uri"}`
`scope`	query	—	scope `{"type":"string","maxLength":2048}`
`state`	query	—	state `{"type":"string","maxLength":1024}`
`nonce`	query	—	nonce `{"type":"string","maxLength":512}`
`code_challenge`	query	—	code_challenge `{"type":"string"}`
`code_challenge_method`	query	—	code_challenge_method `{"type":"string","const":"S256"}`
`response_mode`	query	—	query (default), or query.jwt / jwt (the same for the code flow) for a JWT-secured authorization response (JARM, ADV-002): the redirect carries one parameter, response, a JWT signed by the realm (iss, aud=client_id, exp, code or error, state) and encrypted to the client when it registered authorization_encrypted_response_alg. Errors returned to the redirect use the same mode. `{"type":"string","enum":["query","query.jwt","jwt"]}`
`prompt`	query	—	prompt `{"type":"string"}`
`max_age`	query	—	max_age `{"type":"string"}`
`acr_values`	query	—	acr_values `{"type":"string"}`
`login_hint`	query	—	login_hint `{"type":"string","maxLength":512}`
`ui_locales`	query	—	ui_locales `{"type":"string"}`
`organization`	query	—	Organization hint (ID or slug). `{"type":"string","description":"Organization hint (ID or slug)."}`
`resource`	query	—	RFC 8707 resource indicator; may repeat (at most 5). `{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"},"maxItems":5}],"description":"RFC 8707 resource indicator; may repeat (at most 5)."}`
`request_uri`	query	—	PAR request_uri (urn:ietf:params:oauth:request_uri:...). `{"type":"string","description":"PAR request_uri (urn:ietf:params:oauth:request_uri:...)."}`
`request`	query	—	Request objects are not supported (request_parameter_supported=false). `{"type":"string","description":"Request objects are not supported (request_parameter_supported=false)."}`
`claims`	query	—	The claims parameter is not supported. `{"type":"string","description":"The claims parameter is not supported."}`
`intent`	query	—	Interaction intent hint, e.g. login or register. `{"type":"string","description":"Interaction intent hint, e.g. login or register."}`

Responses

302 Found (redirect)

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Location": {
    "$ref": "#/components/headers/Location"
  },
  "Set-Cookie": {
    "$ref": "#/components/headers/Set-Cookie"
  }
}

400 OAuth 2.0 error (RFC 6749). invalid_client responses use 401 with WWW-Authenticate; throttled requests include Retry-After.

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

Response headers

{
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

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 authorizeGet · Schema definitions · OpenAPI contract

POST/realms/{realm}/oauth/authorize+

Authorization request (form post)

AuthenticationPublic / endpoint-specific credentialsTrust classpublic-protocol-initiationPermissionsSee operation description

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]+$"}`

Request body

application/x-www-form-urlencoded · required

Field	Type	Required	Description
`response_type`	string	—
`client_id`	string	—
`redirect_uri`	string	—
`scope`	string	—
`state`	string	—
`nonce`	string	—
`code_challenge`	string	—
`code_challenge_method`	string	—
`response_mode`	string	—	`query \| query.jwt \| jwt`
`prompt`	string	—
`max_age`	string	—
`acr_values`	string	—
`login_hint`	string	—
`ui_locales`	string	—
`organization`	string	—	Organization hint (ID or slug).
`resource`	oneOf	—	RFC 8707 resource indicator; may repeat (at most 5).
`request_uri`	string	—	PAR request_uri (urn:ietf:params:oauth:request_uri:...).
`request`	string	—	Request objects are not supported (request_parameter_supported=false).
`claims`	string	—	The claims parameter is not supported.
`intent`	string	—	Interaction intent hint, e.g. login or register.

Complete request schema

{
  "type": "object",
  "properties": {
    "response_type": {
      "type": "string",
      "const": "code"
    },
    "client_id": {
      "type": "string"
    },
    "redirect_uri": {
      "type": "string",
      "format": "uri"
    },
    "scope": {
      "type": "string",
      "maxLength": 2048
    },
    "state": {
      "type": "string",
      "maxLength": 1024
    },
    "nonce": {
      "type": "string",
      "maxLength": 512
    },
    "code_challenge": {
      "type": "string"
    },
    "code_challenge_method": {
      "type": "string",
      "const": "S256"
    },
    "response_mode": {
      "type": "string",
      "enum": [
        "query",
        "query.jwt",
        "jwt"
      ]
    },
    "prompt": {
      "type": "string"
    },
    "max_age": {
      "type": "string"
    },
    "acr_values": {
      "type": "string"
    },
    "login_hint": {
      "type": "string",
      "maxLength": 512
    },
    "ui_locales": {
      "type": "string"
    },
    "organization": {
      "type": "string",
      "description": "Organization hint (ID or slug)."
    },
    "resource": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          },
          "maxItems": 5
        }
      ],
      "description": "RFC 8707 resource indicator; may repeat (at most 5)."
    },
    "request_uri": {
      "type": "string",
      "description": "PAR request_uri (urn:ietf:params:oauth:request_uri:...)."
    },
    "request": {
      "type": "string",
      "description": "Request objects are not supported (request_parameter_supported=false)."
    },
    "claims": {
      "type": "string",
      "description": "The claims parameter is not supported."
    },
    "intent": {
      "type": "string",
      "description": "Interaction intent hint, e.g. login or register."
    }
  },
  "additionalProperties": false
}

Responses

302 Found (redirect)

Response headers

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Location": {
    "$ref": "#/components/headers/Location"
  },
  "Set-Cookie": {
    "$ref": "#/components/headers/Set-Cookie"
  }
}

400 OAuth 2.0 error (RFC 6749). invalid_client responses use 401 with WWW-Authenticate; throttled requests include Retry-After.

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

Response headers

{
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

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"
  }
}

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"
  }
}

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 authorizePost · Schema definitions · OpenAPI contract

POST/realms/{realm}/oauth/token+

Token endpoint

Issues tokens for the enabled grants. Parameters must be form-encoded in the body (query parameters are rejected) and must not repeat (except resource). Optional DPoP proof in the DPoP header. When issuance fails for a configuration reason (the client registered response encryption but has no key that can receive it: 400 unauthorized_client; no active signing key: 503 temporarily_unavailable), the issuance is rolled back and the code, device code or refresh token is not consumed, so a retry is not treated as replay.

AuthenticationclientSecretBasic or Trust classpublic-protocol-initiationPermissionsSee operation description

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]+$"}`
`DPoP`	header	—	DPoP proof JWT (RFC 9449). `{"type":"string"}`

Request body

application/x-www-form-urlencoded · required

Field	Type	Required	Description
`client_id`	string	—	Client identifier (client_secret_post, private_key_jwt or public clients).
`client_secret`	string	—	client_secret_post credential. Prefer client_secret_basic.
`client_assertion_type`	string	—
`client_assertion`	string	—	private_key_jwt assertion (audience is the endpoint URL).
`grant_type`	string	Yes	Grants the token endpoint implements; others return unsupported_grant_type. jwt-bearer (RFC 7523) is workload federation (MCH-011, ADV-004): assertion is a workload token from an issuer the client trusts (see /clients/{client}/workload-trusts), and the token issued represents the client's service principal and never outlives the assertion. It is distinct from client authentication with client_assertion. The assertion's jti is spent only when the token is issued (in the issuing transaction), so a request refused for its resource, organization or scope leaves the assertion usable. A refused assertion returns invalid_grant without the reason (the reason is audited as workload.assertion.rejected). `authorization_code \| refresh_token \| client_credentials \| urn:ietf:params:oauth:grant-type:device_code \| urn:ietf:params:oauth:grant-type:token-exchange \| urn:ietf:params:oauth:grant-type:jwt-bearer`
`code`one-time secret	string	—
`redirect_uri`	string	—
`code_verifier`	string	—
`refresh_token`one-time secret	string	—	Refresh tokens rotate on use; reuse revokes the family.
`scope`	string	—
`resource`	oneOf	—
`organization`	string	—
`device_code`one-time secret	string	—
`assertion`one-time secret	string	—	The workload assertion for the jwt-bearer grant.
`subject_token`one-time secret	string	—
`subject_token_type`	string	—
`actor_token`one-time secret	string	—
`requested_token_type`	string	—
`audience`	string	—

Complete request schema

{
  "type": "object",
  "properties": {
    "client_id": {
      "type": "string",
      "description": "Client identifier (client_secret_post, private_key_jwt or public clients)."
    },
    "client_secret": {
      "type": "string",
      "format": "password",
      "description": "client_secret_post credential. Prefer client_secret_basic."
    },
    "client_assertion_type": {
      "type": "string",
      "const": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
    },
    "client_assertion": {
      "type": "string",
      "description": "private_key_jwt assertion (audience is the endpoint URL)."
    },
    "grant_type": {
      "type": "string",
      "enum": [
        "authorization_code",
        "refresh_token",
        "client_credentials",
        "urn:ietf:params:oauth:grant-type:device_code",
        "urn:ietf:params:oauth:grant-type:token-exchange",
        "urn:ietf:params:oauth:grant-type:jwt-bearer"
      ],
      "description": "Grants the token endpoint implements; others return unsupported_grant_type. jwt-bearer (RFC 7523) is workload federation (MCH-011, ADV-004): assertion is a workload token from an issuer the client trusts (see /clients/{client}/workload-trusts), and the token issued represents the client's service principal and never outlives the assertion. It is distinct from client authentication with client_assertion. The assertion's jti is spent only when the token is issued (in the issuing transaction), so a request refused for its resource, organization or scope leaves the assertion usable. A refused assertion returns invalid_grant without the reason (the reason is audited as workload.assertion.rejected)."
    },
    "code": {
      "type": "string",
      "x-secret": true
    },
    "redirect_uri": {
      "type": "string"
    },
    "code_verifier": {
      "type": "string"
    },
    "refresh_token": {
      "type": "string",
      "x-secret": true,
      "description": "Refresh tokens rotate on use; reuse revokes the family."
    },
    "scope": {
      "type": "string"
    },
    "resource": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "organization": {
      "type": "string"
    },
    "device_code": {
      "type": "string",
      "x-secret": true
    },
    "assertion": {
      "type": "string",
      "x-secret": true,
      "description": "The workload assertion for the jwt-bearer grant."
    },
    "subject_token": {
      "type": "string",
      "x-secret": true
    },
    "subject_token_type": {
      "type": "string"
    },
    "actor_token": {
      "type": "string",
      "x-secret": true
    },
    "requested_token_type": {
      "type": "string"
    },
    "audience": {
      "type": "string"
    }
  },
  "required": [
    "grant_type"
  ]
}

Responses

200 OK

application/json

Field	Type	Required	Description
`access_token`one-time secret	string	Yes
`expires_in`	integer	Yes
`id_token`one-time secret	string	—
`issued_token_type`	string	—
`refresh_token`one-time secret	string	—
`scope`	string	—
`token_type`	string	Yes	DPoP for an access token bound to a DPoP key (cnf.jkt, RFC 9449); Bearer for every other token, certificate-bound tokens (cnf.x5t#S256, RFC 8705) included. The same for every grant, token exchange included. `Bearer \| DPoP`

Response headers

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

400 OAuth 2.0 error (RFC 6749). invalid_client responses use 401 with WWW-Authenticate; throttled requests include Retry-After.

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

Response headers

{
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

401 OAuth 2.0 error (RFC 6749). invalid_client responses use 401 with WWW-Authenticate; throttled requests include Retry-After.

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

Response headers

{
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

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"
  }
}

429 OAuth 2.0 error (RFC 6749). invalid_client responses use 401 with WWW-Authenticate; throttled requests include Retry-After.

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

Response headers

{
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

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 token · Schema definitions · OpenAPI contract

POST/realms/{realm}/oauth/introspect+

Token introspection (RFC 7662)

Only confidential clients registered as introspectors for the token audience see active results. API keys (pa_key_) and personal tokens (pa_pat_) are introspected with the same rules.

AuthenticationclientSecretBasic or Trust classresource-serverPermissionsSee operation description

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]+$"}`

Request body

application/x-www-form-urlencoded · required

Field	Type	Required	Description
`client_id`	string	—	Client identifier (client_secret_post, private_key_jwt or public clients).
`client_secret`	string	—	client_secret_post credential. Prefer client_secret_basic.
`client_assertion_type`	string	—
`client_assertion`	string	—	private_key_jwt assertion (audience is the endpoint URL).
`token`one-time secret	string	Yes
`token_type_hint`	string	—

Complete request schema

{
  "type": "object",
  "properties": {
    "client_id": {
      "type": "string",
      "description": "Client identifier (client_secret_post, private_key_jwt or public clients)."
    },
    "client_secret": {
      "type": "string",
      "format": "password",
      "description": "client_secret_post credential. Prefer client_secret_basic."
    },
    "client_assertion_type": {
      "type": "string",
      "const": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
    },
    "client_assertion": {
      "type": "string",
      "description": "private_key_jwt assertion (audience is the endpoint URL)."
    },
    "token": {
      "type": "string",
      "x-secret": true
    },
    "token_type_hint": {
      "type": "string"
    }
  },
  "required": [
    "token"
  ]
}

Responses

200 OK

application/json

Field	Type	Required	Description
`active`	boolean	Yes
`iss`	string	—
`sub`	string	—
`aud`	string	—
`client_id`	string	—
`scope`	string	—
`exp`	integer	—
`iat`	integer	—
`jti`	string	—
`token_kind`	string	—
`token_type`	string	—	DPoP for a token bound to a DPoP key (cnf.jkt, RFC 9449 section 6.2); Bearer otherwise, also for certificate-bound tokens (RFC 8705). `Bearer \| DPoP`
`authz_version`	integer	—
`org_id`	string	—
`sid`	string	—
`auth_time`	integer	—
`acr`	string	—
`act`	object	—
`cnf`	object	—
`agent`	boolean	—	Present (true) when the subject is a service principal registered as an autonomous agent (MCH-017): for its JWT and opaque access tokens and its API keys.
`subject_type`	string	—
`impersonation_grant_id`	string	—

Response headers

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

400 OAuth 2.0 error (RFC 6749). invalid_client responses use 401 with WWW-Authenticate; throttled requests include Retry-After.

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

Response headers

{
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

401 OAuth 2.0 error (RFC 6749). invalid_client responses use 401 with WWW-Authenticate; throttled requests include Retry-After.

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

Response headers

{
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

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 introspect · Schema definitions · OpenAPI contract

POST/realms/{realm}/oauth/revoke+

Token revocation (RFC 7009)

Returns 200 with an empty body for valid and unknown tokens alike.

AuthenticationclientSecretBasic or Trust classpublic-protocol-initiationPermissionsSee operation description

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]+$"}`

Request body

application/x-www-form-urlencoded · required

Field	Type	Required	Description
`client_id`	string	—	Client identifier (client_secret_post, private_key_jwt or public clients).
`client_secret`	string	—	client_secret_post credential. Prefer client_secret_basic.
`client_assertion_type`	string	—
`client_assertion`	string	—	private_key_jwt assertion (audience is the endpoint URL).
`token`one-time secret	string	Yes
`token_type_hint`	string	—	`access_token \| refresh_token`

Complete request schema

{
  "type": "object",
  "properties": {
    "client_id": {
      "type": "string",
      "description": "Client identifier (client_secret_post, private_key_jwt or public clients)."
    },
    "client_secret": {
      "type": "string",
      "format": "password",
      "description": "client_secret_post credential. Prefer client_secret_basic."
    },
    "client_assertion_type": {
      "type": "string",
      "const": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
    },
    "client_assertion": {
      "type": "string",
      "description": "private_key_jwt assertion (audience is the endpoint URL)."
    },
    "token": {
      "type": "string",
      "x-secret": true
    },
    "token_type_hint": {
      "type": "string",
      "enum": [
        "access_token",
        "refresh_token"
      ]
    }
  },
  "required": [
    "token"
  ]
}

Responses

200 OK

Response headers

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

400 OAuth 2.0 error (RFC 6749). invalid_client responses use 401 with WWW-Authenticate; throttled requests include Retry-After.

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

Response headers

{
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

401 OAuth 2.0 error (RFC 6749). invalid_client responses use 401 with WWW-Authenticate; throttled requests include Retry-After.

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

Response headers

{
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

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 revoke · Schema definitions · OpenAPI contract

POST/realms/{realm}/oauth/device_authorization+

Device authorization request (RFC 8628)

AuthenticationclientSecretBasic or Trust classpublic-protocol-initiationPermissionsSee operation description

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]+$"}`

Request body

application/x-www-form-urlencoded · required

Field	Type	Required	Description
`client_id`	string	—	Client identifier (client_secret_post, private_key_jwt or public clients).
`client_secret`	string	—	client_secret_post credential. Prefer client_secret_basic.
`client_assertion_type`	string	—
`client_assertion`	string	—	private_key_jwt assertion (audience is the endpoint URL).
`scope`	string	—
`resource`	oneOf	—

Complete request schema

{
  "type": "object",
  "properties": {
    "client_id": {
      "type": "string",
      "description": "Client identifier (client_secret_post, private_key_jwt or public clients)."
    },
    "client_secret": {
      "type": "string",
      "format": "password",
      "description": "client_secret_post credential. Prefer client_secret_basic."
    },
    "client_assertion_type": {
      "type": "string",
      "const": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
    },
    "client_assertion": {
      "type": "string",
      "description": "private_key_jwt assertion (audience is the endpoint URL)."
    },
    "scope": {
      "type": "string"
    },
    "resource": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    }
  }
}

Responses

200 OK

application/json

Field	Type	Required
`device_code`one-time secret	string	Yes
`expires_in`	integer	Yes
`interval`	integer	Yes
`user_code`	string	Yes
`verification_uri`	string	Yes
`verification_uri_complete`	string	—

Response headers

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

400 OAuth 2.0 error (RFC 6749). invalid_client responses use 401 with WWW-Authenticate; throttled requests include Retry-After.

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

Response headers

{
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

401 OAuth 2.0 error (RFC 6749). invalid_client responses use 401 with WWW-Authenticate; throttled requests include Retry-After.

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

Response headers

{
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

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"
  }
}

429 OAuth 2.0 error (RFC 6749). invalid_client responses use 401 with WWW-Authenticate; throttled requests include Retry-After.

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

Response headers

{
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

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 deviceAuthorization · Schema definitions · OpenAPI contract

POST/realms/{realm}/oauth/par+

Pushed authorization request (RFC 9126)

Requires an authenticated client. request_uri is not allowed in a pushed request; the returned request_uri is single-use and expires after 60 seconds.

AuthenticationclientSecretBasic or Trust classpublic-protocol-initiationPermissionsSee operation description

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]+$"}`

Request body

application/x-www-form-urlencoded · required

Field	Type	Required	Description
`client_id`	string	—
`client_secret`	string	—	client_secret_post credential. Prefer client_secret_basic.
`client_assertion_type`	string	—
`client_assertion`	string	—	private_key_jwt assertion (audience is the endpoint URL).
`response_type`	string	—
`redirect_uri`	string	—
`scope`	string	—
`state`	string	—
`nonce`	string	—
`code_challenge`	string	—
`code_challenge_method`	string	—
`response_mode`	string	—	`query \| query.jwt \| jwt`
`prompt`	string	—
`max_age`	string	—
`acr_values`	string	—
`login_hint`	string	—
`ui_locales`	string	—
`organization`	string	—	Organization hint (ID or slug).
`resource`	oneOf	—	RFC 8707 resource indicator; may repeat (at most 5).
`request`	string	—	Request objects are not supported (request_parameter_supported=false).
`claims`	string	—	The claims parameter is not supported.
`intent`	string	—	Interaction intent hint, e.g. login or register.

Complete request schema

{
  "type": "object",
  "properties": {
    "client_id": {
      "type": "string"
    },
    "client_secret": {
      "type": "string",
      "format": "password",
      "description": "client_secret_post credential. Prefer client_secret_basic."
    },
    "client_assertion_type": {
      "type": "string",
      "const": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
    },
    "client_assertion": {
      "type": "string",
      "description": "private_key_jwt assertion (audience is the endpoint URL)."
    },
    "response_type": {
      "type": "string",
      "const": "code"
    },
    "redirect_uri": {
      "type": "string",
      "format": "uri"
    },
    "scope": {
      "type": "string",
      "maxLength": 2048
    },
    "state": {
      "type": "string",
      "maxLength": 1024
    },
    "nonce": {
      "type": "string",
      "maxLength": 512
    },
    "code_challenge": {
      "type": "string"
    },
    "code_challenge_method": {
      "type": "string",
      "const": "S256"
    },
    "response_mode": {
      "type": "string",
      "enum": [
        "query",
        "query.jwt",
        "jwt"
      ]
    },
    "prompt": {
      "type": "string"
    },
    "max_age": {
      "type": "string"
    },
    "acr_values": {
      "type": "string"
    },
    "login_hint": {
      "type": "string",
      "maxLength": 512
    },
    "ui_locales": {
      "type": "string"
    },
    "organization": {
      "type": "string",
      "description": "Organization hint (ID or slug)."
    },
    "resource": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          },
          "maxItems": 5
        }
      ],
      "description": "RFC 8707 resource indicator; may repeat (at most 5)."
    },
    "request": {
      "type": "string",
      "description": "Request objects are not supported (request_parameter_supported=false)."
    },
    "claims": {
      "type": "string",
      "description": "The claims parameter is not supported."
    },
    "intent": {
      "type": "string",
      "description": "Interaction intent hint, e.g. login or register."
    }
  }
}

Responses

201 Created

application/json

Field	Type	Required	Description
`expires_in`	integer	Yes
`request_uri`	string	Yes

Response headers

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

400 OAuth 2.0 error (RFC 6749). invalid_client responses use 401 with WWW-Authenticate; throttled requests include Retry-After.

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

Response headers

{
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

401 OAuth 2.0 error (RFC 6749). invalid_client responses use 401 with WWW-Authenticate; throttled requests include Retry-After.

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

Response headers

{
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

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 pushAuthorizationRequest · Schema definitions · OpenAPI contract

POST/realms/{realm}/oauth/register+

Dynamic client registration (RFC 7591)

APP-016, ADV-003: only when the realm enables client_registration (404 otherwise). With an initial access token (Bearer) the client receives the non-privileged scopes the token allows; without one, only when the realm allows open registration, and the client is held for approval. Registered clients are third-party clients that ask for consent. 20 registrations per hour per network and 500 per realm (fails closed).

AuthenticationinitialAccessToken or Trust classpublic-protocol-initiationPermissionsSee operation description

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]+$"}`

Request body

application/json · required

Field	Type	Required	Description
`redirect_uris`	array	—
`post_logout_redirect_uris`	array	—
`token_endpoint_auth_method`	string	—	`client_secret_basic \| client_secret_post \| private_key_jwt \| none`
`grant_types`	array	—
`response_types`	array	—
`client_name`	string	—
`scope`	string	—
`contacts`	array	—
`jwks`	object	—
`software_id`	string	—
`software_version`	string	—
`client_uri`	string	—
`logo_uri`	string	—
`policy_uri`	string	—
`tos_uri`	string	—
`rotate_secret`	boolean	—	Management updates only (extension): issue a new client secret; the previous one stays valid for an hour.

Complete request schema

{
  "type": "object",
  "description": "Client metadata (RFC 7591). Unknown members are ignored. Accepted: redirect_uris (1 to 20, exact-match rules), post_logout_redirect_uris, token_endpoint_auth_method (client_secret_basic default, client_secret_post, private_key_jwt with inline jwks, none for public or native clients), grant_types (authorization_code, refresh_token), response_types ([code]), client_name, scope, contacts, jwks, software_id, software_version, client_uri, logo_uri, policy_uri, tos_uri (https, never fetched), frontchannel_logout_uri, response encryption and signing options. Refused: jwks_uri (no metadata fetching), software_statement, other grant and response types.",
  "properties": {
    "redirect_uris": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "post_logout_redirect_uris": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "token_endpoint_auth_method": {
      "type": "string",
      "enum": [
        "client_secret_basic",
        "client_secret_post",
        "private_key_jwt",
        "none"
      ]
    },
    "grant_types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "authorization_code",
          "refresh_token"
        ]
      }
    },
    "response_types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "code"
        ]
      }
    },
    "client_name": {
      "type": "string"
    },
    "scope": {
      "type": "string"
    },
    "contacts": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "jwks": {
      "type": "object"
    },
    "software_id": {
      "type": "string"
    },
    "software_version": {
      "type": "string"
    },
    "client_uri": {
      "type": "string"
    },
    "logo_uri": {
      "type": "string"
    },
    "policy_uri": {
      "type": "string"
    },
    "tos_uri": {
      "type": "string"
    },
    "rotate_secret": {
      "type": "boolean",
      "description": "Management updates only (extension): issue a new client secret; the previous one stays valid for an hour."
    }
  }
}

Responses

201 OK

application/json

Field	Type	Required	Description
`client_id`	string	—
`client_secret`one-time secret	string	—
`client_secret_expires_at`	integer	—
`client_id_issued_at`	integer	—
`registration_access_token`one-time secret	string	—
`registration_client_uri`	string	—
`scope`	string	—
`proudauth_approval_state`	string	—	`approved \| pending`
`proudauth_client_state`	string	—

Response headers

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

400 RFC 7591 error: invalid_redirect_uri, invalid_client_metadata or unapproved_software_statement.

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

401 Missing, invalid, expired, revoked or exhausted token (error invalid_token, WWW-Authenticate Bearer).

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

404 Dynamic registration is not enabled in this realm.

429 Rate limited (code rate_limited). Includes Retry-After; never discloses per-user state.

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"
  }
}

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 registerClient · Schema definitions · OpenAPI contract

GET/realms/{realm}/oauth/register/{client_id}+

Read a registered client (RFC 7592)

Authenticated by the client's registration access token.

AuthenticationregistrationAccessTokenTrust classpublic-protocol-initiationPermissionsSee operation description

Parameters

Name	Location	Required	Details
`realm`	path	Yes	Realm name (path-based issuer). Unknown realms return 404. `{"type":"string"}`
`client_id`	path	Yes	`{"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
`client_id`	string	—
`client_secret`one-time secret	string	—
`client_secret_expires_at`	integer	—
`client_id_issued_at`	integer	—
`registration_access_token`one-time secret	string	—
`registration_client_uri`	string	—
`scope`	string	—
`proudauth_approval_state`	string	—	`approved \| pending`
`proudauth_client_state`	string	—

Response headers

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

400 RFC 7591 error: invalid_redirect_uri, invalid_client_metadata or unapproved_software_statement.

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

401 Missing, invalid, expired, revoked or exhausted token (error invalid_token, WWW-Authenticate Bearer).

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

404 Dynamic registration is not enabled in this realm.

429 Rate limited (code rate_limited). Includes Retry-After; never discloses per-user state.

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"
  }
}

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 readClientRegistration · Schema definitions · OpenAPI contract

PUT/realms/{realm}/oauth/register/{client_id}+

Update a registered client (RFC 7592)

Replaces the registrant's metadata (client_id must match): client_name, redirect and post-logout redirect URIs, grant types, the authentication method within the client type, contacts, software_id/version and the protocol options. The client type and granted scopes cannot change, and settings an administrator controls through the client API (description, security profile and consent settings, offline access, remember-me, default resource, environment, project, owner, subject_type and sector_identifier, login UI and back-channel logout URIs, allowed origins, claim mappings, token_policy) are kept, not reset; metadata that conflicts with them is refused (for example redirect URIs outside a pairwise sector). A new registration_access_token is returned and the old one stops working; rotate_secret=true issues a new secret. The update is one transaction: when any part fails (invalid metadata, or a rotation beyond limits.client_secrets_max, which counts only secrets not yet expired: 409), nothing changes and the presented registration access token stays valid.

AuthenticationregistrationAccessTokenTrust classpublic-protocol-initiationPermissionsSee operation description

Parameters

Name	Location	Required	Details
`realm`	path	Yes	Realm name (path-based issuer). Unknown realms return 404. `{"type":"string"}`
`client_id`	path	Yes	`{"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]+$"}`

Request body

application/json · required

Field	Type	Required	Description
`redirect_uris`	array	—
`post_logout_redirect_uris`	array	—
`token_endpoint_auth_method`	string	—	`client_secret_basic \| client_secret_post \| private_key_jwt \| none`
`grant_types`	array	—
`response_types`	array	—
`client_name`	string	—
`scope`	string	—
`contacts`	array	—
`jwks`	object	—
`software_id`	string	—
`software_version`	string	—
`client_uri`	string	—
`logo_uri`	string	—
`policy_uri`	string	—
`tos_uri`	string	—
`rotate_secret`	boolean	—	Management updates only (extension): issue a new client secret; the previous one stays valid for an hour.

Complete request schema

{
  "type": "object",
  "description": "Client metadata (RFC 7591). Unknown members are ignored. Accepted: redirect_uris (1 to 20, exact-match rules), post_logout_redirect_uris, token_endpoint_auth_method (client_secret_basic default, client_secret_post, private_key_jwt with inline jwks, none for public or native clients), grant_types (authorization_code, refresh_token), response_types ([code]), client_name, scope, contacts, jwks, software_id, software_version, client_uri, logo_uri, policy_uri, tos_uri (https, never fetched), frontchannel_logout_uri, response encryption and signing options. Refused: jwks_uri (no metadata fetching), software_statement, other grant and response types.",
  "properties": {
    "redirect_uris": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "post_logout_redirect_uris": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "token_endpoint_auth_method": {
      "type": "string",
      "enum": [
        "client_secret_basic",
        "client_secret_post",
        "private_key_jwt",
        "none"
      ]
    },
    "grant_types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "authorization_code",
          "refresh_token"
        ]
      }
    },
    "response_types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "code"
        ]
      }
    },
    "client_name": {
      "type": "string"
    },
    "scope": {
      "type": "string"
    },
    "contacts": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "jwks": {
      "type": "object"
    },
    "software_id": {
      "type": "string"
    },
    "software_version": {
      "type": "string"
    },
    "client_uri": {
      "type": "string"
    },
    "logo_uri": {
      "type": "string"
    },
    "policy_uri": {
      "type": "string"
    },
    "tos_uri": {
      "type": "string"
    },
    "rotate_secret": {
      "type": "boolean",
      "description": "Management updates only (extension): issue a new client secret; the previous one stays valid for an hour."
    }
  }
}

Responses

200 OK

application/json

Field	Type	Required	Description
`client_id`	string	—
`client_secret`one-time secret	string	—
`client_secret_expires_at`	integer	—
`client_id_issued_at`	integer	—
`registration_access_token`one-time secret	string	—
`registration_client_uri`	string	—
`scope`	string	—
`proudauth_approval_state`	string	—	`approved \| pending`
`proudauth_client_state`	string	—

Response headers

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

400 RFC 7591 error: invalid_redirect_uri, invalid_client_metadata or unapproved_software_statement.

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

401 Missing, invalid, expired, revoked or exhausted token (error invalid_token, WWW-Authenticate Bearer).

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

404 Dynamic registration is not enabled in this realm.

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"
  }
}

429 Rate limited (code rate_limited). Includes Retry-After; never discloses per-user state.

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"
  }
}

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 updateClientRegistration · Schema definitions · OpenAPI contract

DELETE/realms/{realm}/oauth/register/{client_id}+

Delete a registered client (RFC 7592)

Decommissions the client: its grants and tokens end and its registration access token stops working.

AuthenticationregistrationAccessTokenTrust classpublic-protocol-initiationPermissionsSee operation description

Parameters

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

400 RFC 7591 error: invalid_redirect_uri, invalid_client_metadata or unapproved_software_statement.

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

401 Missing, invalid, expired, revoked or exhausted token (error invalid_token, WWW-Authenticate Bearer).

application/json

Field	Type	Required	Description
`error`	string	Yes
`error_description`	string	—

404 Dynamic registration is not enabled in this realm.

429 Rate limited (code rate_limited). Includes Retry-After; never discloses per-user state.

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"
  }
}

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 deleteClientRegistration · Schema definitions · OpenAPI contract