Update email settings
curl --request PUT \ --url http://localhost:9090/api/v1/admin/settings/email \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "smtpEnabled": true, "smtpHost": "example", "smtpPort": 1, "smtpUsername": "example", "smtpPassword": "example", "clearSmtpPassword": false, "smtpEncryption": "example", "smtpFromName": "example", "smtpFromEmail": "example" }'Update SMTP/email settings. A change needs authserver:manage: these settings decide
where password reset links are sent, so authserver:manage-settings reads them but is
refused a change with 403 MANAGE_SCOPE_REQUIRED. A save with smtpEnabled: false
clears every SMTP field, the stored password included.
The stored SMTP password is kept, replaced or removed:
an absent or empty smtpPassword keeps it, a non-empty one replaces it, and
clearSmtpPassword: true removes it. The two together are refused with 400
handler.settings_email.smtp_password_and_clear.
A stored password reaches only the host it was entered for: a save that changes
smtpHost while a password is stored, carrying neither a new smtpPassword nor
clearSmtpPassword: true, is refused with 400 handler.settings_email.smtp_host_changed
and writes nothing.
The hosts are compared with surrounding space trimmed, one pair of brackets taken off
an IPv6 literal, and without regard to case. A change of port, username, encryption or
sender keeps the stored password.
An empty password with a username is accepted.
Once every other check has passed, a save with smtpEnabled: true opens a TCP
connection to smtpHost on smtpPort, with a 3-second timeout. It only checks that
something answers there: it does not speak SMTP, negotiate TLS or authenticate, which is what
the send-test operation is for. A connection that fails is a 400; see that response.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
At most 254 characters, without a null character. Surrounding space is trimmed.
A new SMTP password, at most 256 bytes, without a null character. The stored password
is never returned, only hasSmtpPassword, so an absent or empty value keeps the stored
password; a non-empty value replaces it. Sending one together with
clearSmtpPassword: true is refused with 400
handler.settings_email.smtp_password_and_clear and nothing is written.
true removes the stored SMTP password. Removing it when none is stored is an ordinary
save. Refused with 400 handler.settings_email.smtp_password_and_clear together with a
non-empty smtpPassword.
Ignored when smtpEnabled is false, which clears every SMTP field, the password included.
How the connection to the SMTP server is encrypted. Certificates are always verified,
against smtpHost.
ssltls, SSL/TLS: TLS from the start of the connection, usually on port 465.starttls, STARTTLS: a plaintext connection upgraded with the STARTTLS command, usually on port 587. A server that does not offer STARTTLS, or whose TLS fails, gets no message.none, STARTTLS if available: upgraded with STARTTLS when the server offers it with a certificate the auth server trusts, and sent unencrypted otherwise. A password is sent only to a server onlocalhost,127.0.0.1or::1, upgraded or not.
Empty or absent is none. Any other value is refused with 400
handler.settings_email.smtp_encryption_invalid. A save with smtpEnabled: false
ignores this field and stores none.
The sender address. It is stored with the part before the @ as sent and the domain lowercased.
Responses
Section titled “Responses”Settings updated
object
How the connection to the SMTP server is encrypted; see the request’s smtpEncryption.
Empty, which a configuration never saved with email on can hold, is none.
Example
{ "smtpEncryption": ""}Error_code is INVALID_REQUEST_BODY for a body that will not parse; a refused field answers its catalog key, such as handler.settings_email.smtp_host_required or validator.email.invalid_format; and a connection that fails answers the key of its cause, such as handler.settings_email.connect_failed_refused. Nothing is written.
A failed connection answers one of these fixed messages, naming at most its coarse cause:
- “Unable to connect to the SMTP server: host name not found.” Check the host name: it is misspelt, or the auth server cannot resolve it, or its resolver did not answer in time. The auth server’s resolver may not be the one your own machine uses.
- “Unable to connect to the SMTP server: connection timed out.” Nothing answered within 3 seconds: check the port, and any firewall between the auth server and the SMTP server.
- “Unable to connect to the SMTP server: connection refused.” The host answered but nothing listens on that port: check the port.
- “Unable to connect to the SMTP server.” Any other failure, such as a network the auth server has no route to.
No address, port or operating-system error is answered; the full error goes to the auth server’s log, at Warn, as “unable to connect to the smtp server” under the request’s request_id.
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"}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.
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"}