Create client
curl --request POST \ --url http://localhost:9090/api/v1/admin/clients \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "clientIdentifier": "example", "description": "example", "displayName": "example", "authorizationCodeEnabled": true, "clientCredentialsEnabled": true }'Create a new OAuth2/OIDC client
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
A user-friendly name for the client (max 100 chars after trimming). When the trimmed value is non-empty, showDisplayName is automatically set to true; otherwise false.
Example generated
{ "clientIdentifier": "example", "description": "example", "displayName": "example", "authorizationCodeEnabled": true, "clientCredentialsEnabled": true}Responses
Section titled “Responses”Client created
object
object
The client’s website URL
A user-friendly name for the client
Read-only. True when the client registered itself through /connect/register
Read-only. True when the client may request the administrative authserver scopes on a user’s behalf; always true for the admin console’s own client. Switched through PUT /api/v1/admin/clients/{id}/administrative-scopes, with authserver:manage alone
When true, the client logo is displayed on sign-in and consent screens
When true, the display name is shown instead of the client identifier
When true, the client description is displayed on sign-in and consent screens
When true, the client website URL is displayed on sign-in and consent screens
Null inherits the global setting, true requires PKCE, false makes it optional. Ignored for public clients, which always require PKCE
Null inherits the global setting, true enables the implicit flow, false disables it. Deprecated in OAuth 2.1
Null inherits the global setting, true enables grant_type=password (RFC 6749 section 4.3), false disables it. Deprecated in OAuth 2.1
Null when this collection was not loaded for the response.
The redirectURIs entries of ClientResponse.
The schema name is unchanged, but the shape below is not what releases up to and
including v1.6.0 put on the wire: this position carried the persistence row directly,
so its keys arrived capitalised and its createdAt arrived as a two-field
{"Time":...,"Valid":...} object. The keys below are the ones every published
contract has always declared.
object
Null when this collection was not loaded or the client has no web origins.
The webOrigins entries of ClientResponse. Its keys moved in the same release and for
the same reason as RedirectURI above.
object
Example generated
{ "client": { "id": 1, "createdAt": "2026-04-15T12:00:00Z", "updatedAt": "2026-04-15T12:00:00Z", "clientIdentifier": "example", "description": "example", "websiteUrl": "example", "displayName": "example", "enabled": true, "consentRequired": true, "createdViaDcr": true, "administrativeScopesAllowed": true, "showLogo": true, "showDisplayName": true, "showDescription": true, "showWebsiteUrl": true, "isPublic": true, "isSystemLevelClient": true, "authorizationCodeEnabled": true, "clientCredentialsEnabled": true, "pkceRequired": true, "implicitGrantEnabled": true, "resourceOwnerPasswordCredentialsEnabled": true, "tokenExpirationInSeconds": 1, "refreshTokenOfflineIdleTimeoutInSeconds": 1, "refreshTokenOfflineMaxLifetimeInSeconds": 1, "includeOpenIDConnectClaimsInAccessToken": "example", "includeOpenIDConnectClaimsInIdToken": "example", "defaultAcrLevel": "example", "redirectURIs": [ { "id": 1, "createdAt": "2026-04-15T12:00:00Z", "uri": "example", "clientId": 1 } ], "webOrigins": [ { "id": 1, "createdAt": "2026-04-15T12:00:00Z", "origin": "example", "clientId": 1 } ] }}Invalid request body or parameters
Admin/account API error envelope. Routing by HTTP status code: 4xx is a client-correctable failure (validation, not found, permission denied, rate limited); 5xx is a server-side problem. The body provides a stable error_code and an error_description for people to read. Protocol endpoints (/auth/token, /auth/authorize, /connect/register, /userinfo) use their RFC-defined error envelopes instead of this one.
object
Stable identifier for the failure. UPPER_SNAKE for legacy codes (e.g. VALIDATION_ERROR), dotted lowercase for catalog-keyed localized codes (e.g. validator.email.required).
A sentence for people to read: in the request’s language when error_code is a catalog key, in English otherwise. Route on error_code, not on this text.
Example generated
{ "error_code": "example", "error_description": "example"}Headers
Section titled “Headers”Bearer challenge when token transport is malformed; ordinary validation errors omit it.
Missing or invalid bearer token
Admin/account API error envelope. Routing by HTTP status code: 4xx is a client-correctable failure (validation, not found, permission denied, rate limited); 5xx is a server-side problem. The body provides a stable error_code and an error_description for people to read. Protocol endpoints (/auth/token, /auth/authorize, /connect/register, /userinfo) use their RFC-defined error envelopes instead of this one.
object
Stable identifier for the failure. UPPER_SNAKE for legacy codes (e.g. VALIDATION_ERROR), dotted lowercase for catalog-keyed localized codes (e.g. validator.email.required).
A sentence for people to read: in the request’s language when error_code is a catalog key, in English otherwise. Route on error_code, not on this text.
Example generated
{ "error_code": "example", "error_description": "example"}Headers
Section titled “Headers”Bearer challenge on token refusals. An operation may also return a handler-level 401 without this header.
The token is valid but does not authorise this request. Four checks answer here, and a caller distinguishes them by error_code.
INSUFFICIENT_SCOPE comes from the route’s authorisation middleware,
before the handler runs: an Admin operation needs one of the scopes
its route names, and an Account operation needs
authserver:manage-account.
USER_CONTEXT_REQUIRED comes from the same middleware on the Account operations, which also require the token to have been issued for a user: one obtained through the client credentials grant carries no auth_time claim and is refused here.
FORBIDDEN comes from the handler, on the account endpoints that resolve a resource by id and then check it belongs to the caller, so a valid token for the wrong user reaches this rather than a 404.
MANAGE_SCOPE_REQUIRED comes from the handler, on the Admin operations
the administrative policy guards. Only authserver:manage creates an
administrator, changes one, or changes what reaches one, so no
granular scope will ever be enough: the remedy is a token holding
authserver:manage, not requesting the route’s scope as for
INSUFFICIENT_SCOPE. An administrator is a user, group or client
holding any of the six administrative permissions (manage,
admin-read, manage-users, manage-clients, manage-settings,
browser-sessions), a user directly or through any of its groups,
the admin console’s own client whatever it holds, and a client
allowed to request the administrative scopes. A granular scope is
refused here when it:
- grants or revokes an administrative permission, directly or by moving a user into or out of a group that holds one, or deletes such a group;
- writes to an administrator user (profile, credentials, enabled, sessions, consents, attributes, memberships, permissions, deletion), an administrative group (settings, attributes, members, permissions, deletion), or an administrator client (settings, authentication, flows, redirect URIs, web origins, token settings, permissions, logo, deletion);
- switches whether a client may request the administrative scopes, on or off, on any client;
- reads an administrator client’s secret;
- changes the email or the audit-log settings;
- changes an administrative permission’s description.
Granular scopes still read administrators. The refusal is answered
after the request’s 400 and 404, writes nothing, carries
WWW-Authenticate: Bearer realm="goiabada", error="insufficient_scope", error_description="...", scope="authserver:manage", and leaves anadministrator_change_refusedaudit record.
Every operation this document secures declares a 403. The public
client logo endpoint, which carries security: [] and authorises
nothing, is the one that does not.
Admin/account API error envelope. Routing by HTTP status code: 4xx is a client-correctable failure (validation, not found, permission denied, rate limited); 5xx is a server-side problem. The body provides a stable error_code and an error_description for people to read. Protocol endpoints (/auth/token, /auth/authorize, /connect/register, /userinfo) use their RFC-defined error envelopes instead of this one.
object
Stable identifier for the failure. UPPER_SNAKE for legacy codes (e.g. VALIDATION_ERROR), dotted lowercase for catalog-keyed localized codes (e.g. validator.email.required).
A sentence for people to read: in the request’s language when error_code is a catalog key, in English otherwise. Route on error_code, not on this text.
Example generated
{ "error_code": "example", "error_description": "example"}Headers
Section titled “Headers”Bearer challenge on scope and administrative-policy refusals; other forbidden responses omit it.
The request failed inside the server, most often a storage error. error_code is INTERNAL_SERVER_ERROR: no detail about the failure, only the request id an operator can find the log line by, and retrying is reasonable. Key rotation’s 500 also answers KEY_SET_INCOMPLETE, which names its cause and no retry clears.
Admin/account API error envelope. Routing by HTTP status code: 4xx is a client-correctable failure (validation, not found, permission denied, rate limited); 5xx is a server-side problem. The body provides a stable error_code and an error_description for people to read. Protocol endpoints (/auth/token, /auth/authorize, /connect/register, /userinfo) use their RFC-defined error envelopes instead of this one.
object
Stable identifier for the failure. UPPER_SNAKE for legacy codes (e.g. VALIDATION_ERROR), dotted lowercase for catalog-keyed localized codes (e.g. validator.email.required).
A sentence for people to read: in the request’s language when error_code is a catalog key, in English otherwise. Route on error_code, not on this text.
Example generated
{ "error_code": "example", "error_description": "example"}