Skip to main content
Version: 0.10

Authentication

The API accepts two kinds of credential:

CredentialSent asBest for
SessionAn HttpOnly cookie set by auth/loginThe console, and interactive tools that sign in like a person
Personal API tokenAuthorization: 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
ParameterRequiredNotes
emailYes
passwordYes
captchaWhen askedA 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.

sessionStateWhat is owedNext call
OKNothing. Fully signed inAny endpoint
LOGIN_MFAThe MFA codePOST auth/mfa
ENFORCE_SET_MFAEnrolling an authenticator, required by an administratorPOST auth/mfa/get, then POST auth/mfa/confirm
ENFORCE_CHANGE_PASSWORDA new password, required by an administratorPOST auth/password_change
REGISTRATION_VERIFICATION_PENDINGConfirming the email address of a self-registered accountThe 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.

note

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​

StepCallParameters
1. Get a new secretPOST auth/mfa/getNone. data.imageBase64 is a PNG of the QR code to scan
2. Confirm itPOST auth/mfa/confirmmfaCode; 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​

CallParametersNotes
POST auth/password_changeoldPassword, newPasswordEnds every other session and returns a fresh cookie
POST auth/password_recoveremail, captcha when configuredQueues a reset email; same answer whether or not the account exists
POST auth/password_recover/set_newtoken (from the link), passwordOne use; ends every session
POST auth/registeremail, name, password, captcha when configuredCreates a new organization, see Self-registration
GET auth/register/enabledNoneWhether self-registration is open. No sign-in needed
POST auth/register/confirmtoken (from the link)Confirms a self-registered account
POST auth/invitation/confirmtoken (from the link), name, passwordAccepts 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"
}
}
}
ParameterRules
name1 to 100 characters after trimming, no control characters
expiresInDays1 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​

LimitDefaultSetting
Longest lifetime365 daysplatformConstants.apiTokenMaxDays
Usable tokens per user20platformConstants.apiTokensPerUser

Expired and revoked tokens do not count towards the 20. There is no token without an expiry.

Listing and revoking​

CallParametersNotes
GET profile/tokens/listNoneYour unrevoked tokens, expired ones included; never the secret
POST profile/tokens/revoketokenIdTakes 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.
Tokens survive password changes

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).

See also​