Skip to main content
Version: 0.16

API Keys

An API key is a long-lived credential used to authenticate against the Stalwart management JMAP API. API keys are intended for automation, scripts, and external tools that need to drive administrative operations such as provisioning accounts, managing domains, or updating configuration objects. They do not grant access to mail protocols: an API key cannot be used to log in over IMAP, POP3, JMAP mail, SMTP submission, or any CalDAV, CardDAV, or WebDAV service. Mail and collaboration protocols continue to authenticate through the account password, an application password, or OAuth.

Each API key is represented by an ApiKey object (found in the WebUI under Account › Credentials › API Keys). An API key belongs to an account and inherits the account's identity when it authenticates; the permissions it may exercise are constrained by its own permission mode rather than by the account's full set of privileges.

Fields​

The credential carries a description that identifies the key in listings, an optional expiresAt that causes the key to stop working after a given date, and an optional list of allowedIps that restricts where the credential may be presented. The secret itself is generated by the server and returned only once, at creation time; it is stored hashed and cannot be recovered afterwards. A createdAt timestamp records when the credential was issued.

Permissions attached to an API key are controlled through the permissions field, which selects one of three modes. In Inherit mode, the key receives the same permissions as the owning account. In Disable mode, the key inherits the account's permissions minus any listed in the accompanying permission list, so a narrower credential can be issued without having to re-enumerate every permission the account holds. In Replace mode, the key is granted only the permissions explicitly listed, regardless of the account's own permissions. The second two modes refer to entries defined on the permissions catalogue and allow a key to be scoped down to the minimum set of operations required by the caller.

Tenant scoping is inherited from the owning account: an API key created by a tenant user can only act within that tenant, and the server rejects requests that attempt to cross tenant boundaries. Roles are likewise resolved through the owning account; the key does not carry an independent list of roles.

Managing keys​

Users create and revoke API keys from the self-service portal, under the API Keys menu option. Administrators can view and revoke keys belonging to any account. The newly generated secret is displayed once at creation and must be stored by the caller; there is no way to retrieve it again from the server.

The maximum number of API keys an account may hold at one time is controlled by maxApiKeys on the Authentication singleton (found in the WebUI under Settings › Authentication › General). When this limit is reached, the user must revoke an existing key before a new one can be issued.

Use with OAuth dynamic registration​

API keys are also the recommended way to authenticate automation that drives OAuth dynamic client registration. A dedicated key granted the authenticate and oauth-client-registration permissions lets an external provisioning system register OAuth clients without using an interactive account.