Endpoints for managing access tokens (authentication sessions and API tokens).
The {tokenName} path parameter is the token's aname value — typically an email address — and must be URL-encoded.
List tokens
Returns all access tokens for the specified account, including primary and secondary (session) tokens.
Response version selection follows the API versions rules. The
v1 schema additionally reports each token's lastuse and expires.
Two token styles exist: primary tokens (for API access — require acl,
aname, apass, primary) and session tokens (browser sign-in — use
<sessionkey/> with optional lifetime).
path Parameters
accountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
Headers
AcceptList tokens › Responses
Create token
Creates a new access token. Two styles are supported:
Primary-style token (for API access): requires acl, aname, apass,
and primary fields. The descr field is optional.
Session token (browser sign-in): uses <sessionkey/> with an optional
lifetime (ISO 8601 duration).
<sessionkey/> may not be supported in all API versions (returns 400).
Every account has at least one primary token. It is created together with the account, acts as the account's sign-in identity, and normally lives as long as the account itself. A secondary(session) token is a credential created under an existing token — for example a session token created at browser sign-in, or an API token used by an integration — and is typically given a limited lifetime.
Token permissions
No token can create a token more privileged than itself: the new token's
ACL must be covered by the creator's effective ACL, otherwise the API
returns 403 Effective token ACL must dominate created token ACL.
When the create request contains no <acl> (or legacy <type>), the new token
receives the creator's ACL as written, not a copy of the resolved
permissions. If the creator's ACL is a named role such as MasterAdmin, the new
token references the same role — editing the MasterAdmin role later changes
the permissions of the creator and of the secondary token.
Token lifetime and expiration
Both fields are optional, independent, and behave the same for primary and secondary tokens:
lifetime— ISO 8601 duration, for exampleP30DorPT12H. Idle period after which an unused token is blocked; every successful authentication restarts the idle window.expires— ISO 8601 UTC timestamp, for example2027-01-01T00:00:00Z. Exact date and time when the token expires, independent of use; must lie in the future when creating.
If neither field is supplied, the token never expires. If both are supplied,
the token expires when the first of the two limits is reached. A secondary
token also expires when its primary token is deleted or expires.
The fields lifetime, lastuse, and expires appear in list responses from API v1.
path Parameters
accountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
Headers
AcceptCreate token › Responses
Delete all secondary tokens
Deletes all non-primary (secondary) tokens that belong to the authenticated token's tree. The primary token is preserved.
Authenticated token
The authenticated token is the token whose credentials are supplied in the request. Deletion is scoped to the primary token at the root of the authenticated token's tree: every secondary token in that primary's tree is removed, including secondary tokens created by other secondary tokens deeper in the hierarchy. An account may hold several primary tokens, each with its own tree; secondary tokens under a different primary are left untouched.
Authenticating with a secondary token gives the same scope, because the server first resolves the primary token at the root of its tree. The authenticated secondary token is therefore deleted as well.
Grandchild tokens
A secondary token may itself create secondary tokens, so a token tree can be deeper than one level. Deleting a secondary token also removes every token created beneath it, to any depth. The response does not report how many tokens were removed.
path Parameters
accountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
Delete all secondary tokens › Responses
success
Update token
Updates a token's properties. Include only the fields you want to change.
The {tokenName} in the path must be URL-encoded (e.g. user%40example.com).
Update token ACL
The new acl must be covered by the authenticated token's effective ACL — a
token cannot grant permissions it does not hold itself. If the new acl
contains a permission the authenticated token lacks, the request is rejected.
Changing a token's acl deletes all secondary tokens beneath the updated
token, no matter how deep they are. This ensures no secondary token retains permissions wider than its
parent's new ACL. The deletion is irreversible and happens only when the new
acl value differs from the stored one; updates to other fields do not
trigger it.
Token credentials invalidation
Every PUT — regardless of which field changes — discards the cached
credentials of the updated token and of every secondary token created under
it, at any depth. Each affected token is re-validated against the database on
its next request, so credential changes take effect immediately.
path Parameters
accountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
tokenNameUpdate token › Responses
Delete token
Deletes a specific token by its aname (logout).
The {tokenName} in the path must be URL-encoded (e.g. user%40example.com).
Secondary tokens are deleted too
Deleting a token also deletes every secondary token created under it — directly, or by other secondary tokens further down, at any depth. Primary tokens are never removed this way: a primary token is always the root of its own tree, even when another token created it. The response does not report how many tokens were removed.
Delete token permissions
- A primary token can delete any secondary token in its tree, but cannot delete itself.
- A secondary token can delete itself or any other secondary token in the same tree, but cannot delete its primary token.
- A token whose ACL includes the
ChangeSiblingTokenspermission (granted asG/ChangeSiblingTokensin the token's ACL) can also delete tokens outside its own tree.
path Parameters
accountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
tokenNameDelete token › Responses
Get token contacts
Returns contact information associated with a token.
Only works with primary tokens — returns 404 for non-primary tokens.
path Parameters
accountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
tokenNameGet token contacts › Responses
Update token contacts
Sets or updates contact information on a token.
Only works with primary tokens — returns 404 for non-primary tokens.
path Parameters
accountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
tokenNameUpdate token contacts › Responses
Get token attribute
Returns the value of a specific attribute on a token.
Token attributes are free-form key-value storage for auxiliary client information. Attribute names are arbitrary and carry no server-side meaning.
Only works with primary tokens — non-primary tokens are treated as not found.
Known bug: the response XML does not include the <?xml?> declaration.
The keys below are examples used by Keepit's own clients:
| Attribute | Response value | Description |
|---|---|---|
enable-notification | true or false | Whether email notifications are enabled |
release_version | version string (e.g. 10.17.0) | Tracks which "What's new" version the user has seen |
path Parameters
accountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
tokenNameattributeNameGet token attribute › Responses
success
Set token attribute
Sets or updates a specific attribute on a token.
Token attributes are free-form key-value storage for auxiliary client information. Attribute names are arbitrary and carry no server-side meaning.
Only works with primary tokens — non-primary tokens are treated as not found.
The keys below are examples used by Keepit's own clients:
| Attribute | Body value | Description |
|---|---|---|
enable-notification | <attribute><value>true</value></attribute> or false | Enable/disable email notifications |
release_version | <attribute><value>{version}</value></attribute> | Set the "What's new" version seen |
path Parameters
accountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
tokenNameattributeNameSet token attribute › Responses
success
Delete token attribute
Deletes a specific attribute from a token.
Token attributes are free-form key-value storage for auxiliary client information. Attribute names are arbitrary and carry no server-side meaning.
Only works with primary tokens — non-primary tokens are treated as not found.
The keys below are examples used by Keepit's own clients:
| Attribute | Effect of deletion |
|---|---|
enable-notification | Removes notification preference (reverts to default) |
release_version | Triggers the "What's new" popup on the user's next login |
path Parameters
accountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
tokenNameattributeNameDelete token attribute › Responses
success
Send activation email
Sends an activation email to the specified token's email address.
path Parameters
accountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).