Settings API

All Settings routes require a Ration bearer token and operate only on the authenticated user. Paths below are relative to /apis/v1.

Authorization: Bearer <ration_access_token>
Content-Type: application/json

Use the normalized /settings/... routes in new integrations. Legacy /app/settings/... aliases remain only for compatibility and are not part of this reference.

Profile

Read the current profile

GET /settings/profile

Response field	Type	Description
id	string	Authenticated user's identifier.
username	string	User's sign-in address.
tenant_id	string	Tenant containing the account.
name	string	Display name, when set.
language	string	Preferred language, when set.
tags, metaData	array / object	Profile metadata, when present.

The response is the current user object. Treat unlisted fields as extensible and do not depend on them without checking their presence.

Update the current profile

PUT /settings/profile

Request field	Type	Required	Description
user	object	Yes	Profile fields to change.
user.name	string	No	Display name.
user.language	string	No	Language preference.
user.tags	array	No	Profile tags.
user.encryptMessages	boolean	No	Request message encryption preference.
user.encryptForwarded	boolean	No	Request forwarding-encryption preference.
user.pubKey	string	No	Public key material.
user.metaData	object	No	Application metadata.
user.fromWhitelist	array	No	Allowed sender addresses.

{
  "user": {
    "name": "Ada Okafor",
    "language": "en"
  }
}

Returns the updated user object. Fields outside this allowlist, including account identity, tenant, quota, and password fields, are ignored.

Deactivate the current account

DELETE /settings/profile

Returns 200 with the string Account deactivated when successful. This is an account-level action: integrations should require an explicit user confirmation before sending it.

General preferences

Method	Path	Request fields	Response
GET	/settings/general-preferences	—	{ "success": true, "preferences": Preferences }
PUT	/settings/general-preferences	A partial preferences object, or the same fields at the top level.	{ "success": true, "preferences": Preferences }

Preferences always contains the following fields. Blank strings mean that no preference has been selected.

Field	Type	Description
continent	string	Geographic region.
country	string	Country selection.
language	string	Preferred locale/language.
date_format	string	Date format preference. dateFormat is accepted as an input alias.
time_format	string	Time format preference. timeFormat is accepted as an input alias.

{
  "preferences": {
    "country": "Nigeria",
    "language": "en",
    "date_format": "DD/MM/YYYY",
    "time_format": "HH:mm"
  }
}

Notification preferences

Method	Path	Request	Response
GET	/settings/notifications	—	{ "success": true, "preferences": object, "known_modules": string[], "known_types": string[] }
PUT	/settings/notifications	A partial preferences object, either inside preferences or at the top level.	{ "success": true, "preferences": object }

Send only the notification settings that should change. Ration retains the user's other settings and returns the effective, merged preference map.

{
  "preferences": {
    "mail": { "enabled": true },
    "chat": { "enabled": false }
  }
}

Use known_modules and known_types from the read response to build a compatible preference editor rather than hard-coding a list.

Mail signatures

A signature has id, name, signature_text, signature_html, priority, and inserted_at fields. priority: true marks the default signature.

Method	Path	Request fields	Response
GET	/settings/signatures	—	{ "results": [Signature] }
POST	/settings/signatures	{ "signature": { "name", "signature_text", "signature_html", "priority" } }	Created signature object.
GET	/settings/signatures/:id	—	Signature
PUT	/settings/signatures/:id	{ "signature": { "name", "signature_text", "signature_html", "priority" } }	Updated signature object.
PUT	/settings/signatures/:id/default	—	Updated signature object.
DELETE	/settings/signatures/:id	—	"Signature Deleted"

The authenticated user's tenant and owner identifiers are always set server-side. Supplying them in a request cannot move or take over a signature.

Security and password changes

Read security state

GET /settings/security

Returns:

{
  "status": "success",
  "security": {
    "enable2fa": true
  }
}

security can include additional account-security fields. Treat it as a read-only, extensible object.

Change the sign-in password

PUT /settings/password

Request field	Type	Required	Description
existingPassword	string	Yes	Current password.
password	string	Yes	New password.
otp or token	string, or { "token": string }	When 2FA is enabled	Current TOTP code.

The new password must be at least 12 characters and include lowercase, uppercase, and a number or supported symbol. With 2FA enabled, a current authentication code is required. A successful response is 200 Successful; the client should clear locally stored credentials and require the user to sign in again.

Two-factor authentication (TOTP)

Two-factor routes use the /auth namespace because they act on session authentication. They are still protected API routes.

Method	Path	Request	Success response
POST	/auth/initiate-2fa	—	{ "status": "success", "otp_uri": "otpauth://…", "message": "…" }
POST	/auth/enable-2fa	{ "otp": "123456" } or { "otp": { "token": "123456" } }	{ "status": "success", "backup_codes": string[], "redirect_to": "…" }
POST	/auth/verify-2fa	Same token shape as enable.	{ "status": "success", "token": "…" }
POST	/auth/disable-2fa	—	{ "status": "success", "message": "2FA successfully disabled" }

otp_uri is a setup secret. Render it only as a QR code or pass it directly to a trusted authenticator-app hand-off; never write it to logs, analytics, telemetry, or persistent client storage.

Ration has been tested with 2FAS and uses standard TOTP, so compatible clients include Google Authenticator, Microsoft Authenticator, Authy, 1Password, Bitwarden, and similar TOTP apps. Enabling 2FA returns backup codes and requires a fresh sign-in. Store the backup codes securely and separately from the password.

The historic spelling POST /auth/initate-2fa remains available for older clients, but new integrations must use /auth/initiate-2fa.

Application-specific passwords

After 2FA is enabled, IMAP, POP3, and SMTP clients must authenticate with an application-specific password, not the main account password. Create one password per mail client or device, reveal/store it only during creation, and delete it when that client no longer needs access.

Method	Path	Request	Response
GET	/settings/application-passwords	—	Application-password list. The secret value is not returned.
POST	/settings/application-passwords	ApplicationPasswordRequest	Created application-password record, including the generated secret when applicable.
DELETE	/settings/application-passwords/:asp_id	—	Deletion result.

ApplicationPasswordRequest fields:

Field	Type	Required	Description
description	string	Recommended	Recognisable client/device label. name is accepted as an alias.
scopes	string[]	Recommended	Mail-client permissions: imap, pop3, smtp, or the all-except-master scope provided by the service. scope is accepted as a one-value alias.
password	string	No	Optional client-chosen 16-letter password. It must contain exactly 16 ASCII letters; omit it to generate a password.
address	string	No	Address to associate with the credential when supported.
ttl	integer	No	Credential lifetime when supported.
generateMobileconfig	boolean	No	Request a client configuration payload when supported.

Do not log the create response or send the application-specific password through chat or email. It is a credential with the same handling requirements as a password.

Errors

Status	Meaning
401	Missing or invalid bearer token.
403	Current user is not permitted to complete the security or application-password operation.
404	Signature or application password does not exist for the current user.
422	Invalid signature ID, invalid application-password request, weak password, or missing/invalid TOTP token.
500	An unexpected service error while processing a profile or signature action.