Authentication
The API accepts two kinds of credential:
| Credential | Sent as | Best for |
|---|---|---|
| Session | An HttpOnly cookie set by auth/login | The console, and interactive tools that sign in like a person |
| Personal API token | Authorization: Bearer le_… | Scripts, scheduled jobs and integrations |
Both act as the user they belong to: every permission, account state and module check is the same. If a request carries both a session cookie and a bearer token, the cookie is used and the token is ignored.
For scripts, use a personal API token. It needs no sign-in handshake, works with MFA-protected accounts, and can be revoked on its own.
Signing in with a session
curl -X POST 'https://<host>/api/v1/auth/login' \
--data-urlencode 'email=ada@contoso.com' \
--data-urlencode "password=$VELUM_PASSWORD" \
--cookie-jar cookies.txt
| Parameter | Required | Notes |
|---|---|---|
email | Yes | |
password | Yes | |
captcha | When asked | A CAPTCHA token, required once sign-in has started failing on a deployment with CAPTCHA configured, see CAPTCHA |
A successful answer sets the session cookie and returns the user with the state of the new session:
{
"status": true,
"message": null,
"data": {
"id": "3f2b8c1e-5d7a-4e90-b6a1-0c9d2e7f4a15",
"email": "ada@contoso.com",
"name": "Ada Lovelace",
"state": "ENABLED",
"mfaEnabled": true,
"mfaEnforce": false,
"passwordChangeEnforce": false,
"emailVerified": true
},
"sessionState": "LOGIN_MFA"
}
(The data object carries more profile fields than shown.)
A failed sign-in answers HTTP 401 with status: false. The message is the
same, "Incorrect username or password", for an unknown address and a wrong
password. A correct password on a blocked account gets "User cannot login". Repeated failures lock the
address out, see Account security.
Send the cookie jar on every following request:
curl 'https://<host>/api/v1/profile/me' --cookie cookies.txt
The cookie cannot be read by page scripts (HttpOnly), is sent over HTTPS only
by default (Secure) and is SameSite=Lax. Its lifetime is set by the
deployment and counted from sign-in; activity does not extend it, see
Sessions.
Session states
sessionState says whether the session is fully signed in or still owes a
step. Until it is OK, every other endpoint answers HTTP 403.
sessionState | What is owed | Next call |
|---|---|---|
OK | Nothing. Fully signed in | Any endpoint |
LOGIN_MFA | The MFA code | POST auth/mfa |
ENFORCE_SET_MFA | Enrolling an authenticator, required by an administrator | POST auth/mfa/get, then POST auth/mfa/confirm |
ENFORCE_CHANGE_PASSWORD | A new password, required by an administrator | POST auth/password_change |
REGISTRATION_VERIFICATION_PENDING | Confirming the email address of a self-registered account | The link in the confirmation email; POST auth/register/confirm/resend to send another |
Each of these calls answers with a fresh cookie and the next sessionState, so
keep updating the cookie jar (--cookie cookies.txt --cookie-jar cookies.txt)
until it reads OK.
ACCOUNT_BLOCKED also exists in the state list, but sign-in does not currently
issue it: a blocked account is refused at sign-in instead.
Multi-factor authentication
Answering the MFA challenge
When sign-in returns LOGIN_MFA, send the six-digit code from the authenticator
app:
curl -X POST 'https://<host>/api/v1/auth/mfa' \
--data-urlencode 'code=123456' \
--cookie cookies.txt --cookie-jar cookies.txt
Wrong codes are limited to 5 per user before a 15-minute lockout (defaults).
Enrolling an authenticator
| Step | Call | Parameters |
|---|---|---|
| 1. Get a new secret | POST auth/mfa/get | None. data.imageBase64 is a PNG of the QR code to scan |
| 2. Confirm it | POST auth/mfa/confirm | mfaCode; password too, except in the ENFORCE_SET_MFA state right after sign-in |
Enrolment is refused if a factor is already enrolled. Confirming ends every other session of the account.
Turning MFA off
POST auth/mfa/disable with password and mfaCode, from a fully signed-in
session. It is refused while an administrator enforces MFA on the account, and
ends every other session.
Signing out
curl -X POST 'https://<host>/api/v1/auth/logout' \
--cookie cookies.txt --cookie-jar cookies.txt
The session is ended on the server: its token is refused from the next request on, wherever a copy of it is. Your other sessions carry on. The call always succeeds and clears the cookie, even for a cookie that is already invalid.
Other account calls
| Call | Parameters | Notes |
|---|---|---|
POST auth/password_change | oldPassword, newPassword | Ends every other session and returns a fresh cookie |
POST auth/password_recover | email, captcha when configured | Queues a reset email; same answer whether or not the account exists |
POST auth/password_recover/set_new | token (from the link), password | One use; ends every session |
POST auth/register | email, name, password, captcha when configured | Creates a new organization, see Self-registration |
GET auth/register/enabled | None | Whether self-registration is open. No sign-in needed |
POST auth/register/confirm | token (from the link) | Confirms a self-registered account |
POST auth/invitation/confirm | token (from the link), name, password | Accepts an invitation |
Reset, confirmation and invitation links are delivered by email, which works only when email sending is set up for the deployment (off by default).
CAPTCHA
GET auth/captcha (no sign-in needed) returns the CAPTCHA provider and public
site key, or nulls when the deployment has none. Where one is configured, the
token from the provider's widget is sent as captcha on auth/register,
auth/password_recover, and auth/login after 3 recent failures (default). A
script that signs in with a password can hit this; use an API token instead.
Personal API tokens
A personal API token is a secret a user creates to call the API as themselves
from a script. It starts with le_.
Creating a token
The usual way is the console: Profile settings → API tokens → Create token, see Your profile. The token is shown once.
The same can be done through the API, but only from a signed-in session, not with another token:
curl -X POST 'https://<host>/api/v1/profile/tokens/create' \
--data-urlencode 'name=Nightly export' \
--data-urlencode 'expiresInDays=90' \
--cookie cookies.txt
{
"status": true,
"message": null,
"data": {
"token": "le_…",
"entry": {
"id": "9a41d0c2-2f6b-4c11-8e3d-5b7a0f1c6e28",
"name": "Nightly export",
"prefix": "le_Xb3kQ9pZr",
"created": 1794787200,
"expires": 1802563200,
"lastUsed": null,
"state": "ACTIVE"
}
}
}
| Parameter | Rules |
|---|---|
name | 1 to 100 characters after trimming, no control characters |
expiresInDays | 1 to 365 by default. The console offers 30, 90, 180 and 365 |
Times are Unix timestamps in seconds. data.token appears only in this answer;
the server stores a hash.
Using a token
export VELUM_TOKEN='le_…'
curl 'https://<host>/api/v1/profile/me' \
-H "Authorization: Bearer $VELUM_TOKEN"
curl -G 'https://<host>/api/v1/assets/list' \
-H "Authorization: Bearer $VELUM_TOKEN" \
--data-urlencode 'tenantId=<tenant-uuid>' \
--data-urlencode 'type=ENDPOINTS' \
--data-urlencode 'query=' \
--data-urlencode 'page=0' \
--data-urlencode 'size=200'
Do not send a session cookie with the token: the cookie would take precedence.
Requests with a token pass the cross-site check
as long as your client sends no browser Origin, Referer or Sec-Fetch-Site
header naming another site.
An unknown, expired or revoked token gets HTTP 401. The token's last use is recorded, at most once a minute by default.
Limits
| Limit | Default | Setting |
|---|---|---|
| Longest lifetime | 365 days | platformConstants.apiTokenMaxDays |
| Usable tokens per user | 20 | platformConstants.apiTokensPerUser |
Expired and revoked tokens do not count towards the 20. There is no token without an expiry.
Listing and revoking
| Call | Parameters | Notes |
|---|---|---|
GET profile/tokens/list | None | Your unrevoked tokens, expired ones included; never the secret |
POST profile/tokens/revoke | tokenId | Takes effect from the next request; cannot be undone |
Both need a signed-in session.
What a token cannot do
- Manage tokens.
profile/tokens/*refuse bearer tokens (HTTP 401), so a leaked token cannot create more tokens or extend itself. - Act outside its user's rights. It has exactly the user's permissions, which change when the user's roles change.
- Act while the user is blocked. Requests get HTTP 403 while the account is Suspended; they work again if it is unblocked. Deleting the user ends the token for good.
- Stand in for a sign-in step. A token is only accepted where a fully signed-in session would be.
Changing the password, resetting it or turning MFA on or off does not revoke a user's tokens. After a suspected compromise, revoke them explicitly.
Authorisation
Authentication establishes who you are; the role model decides what you may do. A request that is authenticated but not permitted is refused with HTTP 403 (for a missing global permission) or a handled failure in the envelope (for a missing tenant permission or a tenant you have no role in).