Enable/disable OTP
curl --request PUT \ --url http://localhost:9090/api/v1/account/otp \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "enabled": true, "password": "example", "otpCode": "example" }'Enables or disables TOTP for the authenticated user. Requires password verification, and when enabling, a current code from the authenticator.
A wrong or blank password is refused with 400 (AUTHENTICATION_FAILED). A wrong password
counts against the account_password rate limit, shared with the account’s password,
email and recovery-code changes and its deletion. Every request counts against the
account_credential_change rate limit, 10 per hour per account, shared with the account’s
password change and new sets of recovery codes.
Enabling completes the enrollment issued by GET /api/v1/account/otp/enrollment: the code
is verified against the seed the server issued and that seed is what gets enrolled. Call the
enrollment endpoint first. Returns 400 if no enrollment is pending or the one started has
expired (OTP_ENROLLMENT_NOT_PENDING).
The code is accepted from the authenticator’s current 30-second step or the one before it.
The code of the step after, which only a device whose clock runs ahead shows, is refused
with 400 (OTP_CLOCK_AHEAD), whose error_description asks the user to check the device’s
time. Nothing is spent by it, so the next code the authenticator shows still enables.
This request must not carry a secretKey. One that does is refused with 400
(SECRET_KEY_NOT_ACCEPTED) rather than having the field ignored, because a caller sending
one believes it is choosing which authenticator is installed, and it is not.
The change lands only while the authenticator is still as this request read it. When
another request changed it in between, the answer is read from the account as it is now:
400 (OTP_ALREADY_ENABLED or OTP_NOT_ENABLED) when OTP is already in the state asked
for, otherwise 409 (CONCURRENT_UPDATE) with nothing saved. The code submitted with an
enable is spent either way.
An enable answers with recoveryCodes: the ten recovery codes created with the new
authenticator, each of which signs the user in once in place of an authenticator code.
This response is the only time they are returned, since the server stores only their
hashes, so show them to the user now. A disable answers without the field and deletes the
user’s recovery codes with the authenticator.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
Current password for verification
6-digit TOTP code (required when enabling), generated from the secret returned by GET /api/v1/account/otp/enrollment
Example generated
{ "enabled": true, "password": "example", "otpCode": "example"}Responses
Section titled “Responses”OTP status updated
object
object
“female”, “male” or “other”, or empty when unset
The user’s language and region, such as fr-CA, which applications receive as the locale claim, or empty when unset.
The language the user chose for Goiabada’s own pages and emails: the tag of one of Goiabada’s built-in languages, such as pt-BR, or empty for Automatic, where pages follow the language the application or the browser asks for and emails follow locale.
ISO 3166-1 alpha-2 country code (e.g. US, BR), or empty string.
True while the user’s authenticator is disabled because 100 one-time codes in a row were refused. otpEnabled stays true, and every code is refused, the right one included, until two-factor authentication is turned off for the user and they set up a new authenticator. Someone who knew the user’s password, or held one of their sessions, sent those codes, so set a new password (PUT /api/v1/admin/users/{id}/password) before turning two-factor authentication off (PUT /api/v1/admin/users/{id}/otp): otherwise the old password alone signs in.
Present only when the request turned two-factor authentication on: the ten recovery codes created with the authenticator, each 24 characters in six groups of four, such as 7kq2-m9xh-4trw-b3np-j6vd-egac. Returned this once and never again.
Example generated
{ "user": { "id": 1, "createdAt": "2026-04-15T12:00:00Z", "updatedAt": "2026-04-15T12:00:00Z", "enabled": true, "subject": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "username": "example", "givenName": "example", "middleName": "example", "familyName": "example", "nickname": "example", "website": "example", "gender": "example", "emailVerified": true, "zoneInfoCountryName": "example", "zoneInfo": "example", "locale": "example", "pageLanguage": "example", "birthDate": "2026-04-15T12:00:00Z", "phoneNumberCountryUniqueId": "example", "phoneNumberCountryCallingCode": "example", "phoneNumber": "example", "phoneNumberVerified": true, "addressLine1": "example", "addressLine2": "example", "addressLocality": "example", "addressRegion": "example", "addressPostalCode": "example", "addressCountry": "example", "otpEnabled": true, "otpAuthenticatorDisabled": true }, "recoveryCodes": [ "example" ]}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 codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.
A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.
A JSON Pointer (RFC 6901) to the member of the request body the refusal is about,
such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand.
Left out when the refusal names no member. It’s set by the refusals of a brand’s footer
links, palette and custom CSS, and of an email template’s text and brandId.
Example generated
{ "error_code": "example", "error_description": "example", "error_field": "example"}Headers
Section titled “Headers”Bearer challenge when token transport is malformed; ordinary validation errors omit it.
Missing or invalid access token (ACCESS_TOKEN_REQUIRED, INVALID_TOKEN), or a refused DPoP proof (INVALID_DPOP_PROOF)
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 codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.
A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.
A JSON Pointer (RFC 6901) to the member of the request body the refusal is about,
such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand.
Left out when the refusal names no member. It’s set by the refusals of a brand’s footer
links, palette and custom CSS, and of an email template’s text and brandId.
Example generated
{ "error_code": "example", "error_description": "example", "error_field": "example"}Headers
Section titled “Headers”A Bearer challenge, then a DPoP challenge naming the accepted proof algorithms, on
token refusals, the error in the challenge of the scheme the token was sent with:
Bearer realm="goiabada", error="invalid_token", error_description="...", DPoP realm="goiabada", algs="ES256 ...". An operation may also return a handler-level
401 without this header.
The token is valid but does not authorise this request. A caller tells the refusals apart 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.
CLIENT_NOT_ALLOWED comes from the route on the two Account
operations only the admin console’s own client may call,
deleteAccount and exportAccount. ACCOUNT_DELETION_DISABLED comes
from deleteAccount while an administrator has turned off Let
users delete their own account.
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, sign-out redirect URIs, back-channel logout, DPoP, web origins, token settings, permissions, introspection resources, logo, deletion);
- switches whether a client may request the administrative scopes, on or off, on any client;
- adds the
authserverresource to a client’s introspection resources; - reads an administrator client’s secret, or reads or sets the
secret of a client listed for the
authserverresource among its introspection resources; - sets or changes a client’s back-channel logout URI;
- 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 the insufficient_scope challenge of
the scheme the token was sent with, such as
WWW-Authenticate: Bearer realm="goiabada", error="insufficient_scope", error_description="...", scope="authserver:manage", and leaves anadministrator_change_refusedaudit record.
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 codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.
A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.
A JSON Pointer (RFC 6901) to the member of the request body the refusal is about,
such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand.
Left out when the refusal names no member. It’s set by the refusals of a brand’s footer
links, palette and custom CSS, and of an email template’s text and brandId.
Example generated
{ "error_code": "example", "error_description": "example", "error_field": "example"}Headers
Section titled “Headers”An insufficient_scope challenge in the scheme the token was sent with, Bearer or DPoP, on every refusal but FORBIDDEN and ACCOUNT_DELETION_DISABLED, which omit it.
Resource not found
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 codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.
A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.
A JSON Pointer (RFC 6901) to the member of the request body the refusal is about,
such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand.
Left out when the refusal names no member. It’s set by the refusals of a brand’s footer
links, palette and custom CSS, and of an email template’s text and brandId.
Example generated
{ "error_code": "example", "error_description": "example", "error_field": "example"}Another request changed the account’s authenticator after this one read it. error_code is CONCURRENT_UPDATE; nothing was saved. Read the account again and retry.
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 codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.
A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.
A JSON Pointer (RFC 6901) to the member of the request body the refusal is about,
such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand.
Left out when the refusal names no member. It’s set by the refusals of a brand’s footer
links, palette and custom CSS, and of an email template’s text and brandId.
Example generated
{ "error_code": "example", "error_description": "example", "error_field": "example"}Rate limit reached. Every limit on the account API is counted by the token’s user and applies whether or not the rate limiter (GOIABADA_AUTHSERVER_RATELIMITER_ENABLED) is on. error_code is TOO_MANY_REQUESTS and a Retry-After header carries the window length in seconds.
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 codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.
A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.
A JSON Pointer (RFC 6901) to the member of the request body the refusal is about,
such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand.
Left out when the refusal names no member. It’s set by the refusals of a brand’s footer
links, palette and custom CSS, and of an email template’s text and brandId.
Example generated
{ "error_code": "example", "error_description": "example", "error_field": "example"}Headers
Section titled “Headers”Seconds to wait before retrying
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 codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.
A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.
A JSON Pointer (RFC 6901) to the member of the request body the refusal is about,
such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand.
Left out when the refusal names no member. It’s set by the refusals of a brand’s footer
links, palette and custom CSS, and of an email template’s text and brandId.
Example generated
{ "error_code": "example", "error_description": "example", "error_field": "example"}