User authorization

Purpose

Use this call to obtain a user token. A user token represents a signed-in dashboard user. Send it in the token header of operations that act on behalf of that user, such as the token methods. For server-to-server calls use a permanent API token instead.

Request

POST <API_BASE_URL>/user/login. All calls are POST under your API address. Replace <API_BASE_URL> with the API address provided with your access.

This operation needs no token. It is the call that issues one.

Content type: application/json.

Field	Type	Required	Description
`email`	string	yes	The email address of the dashboard user.
`password`	string	yes	The password of the dashboard user.
`valid_days`	number	no	How many days the token stays valid. Used when the account group sets no lifetime of its own.

Response

HTTP 200. The credentials were accepted.

Field	Type	Description
`status`	string	Always `ok` here.
`token`	string	The user token. Send it as the `token` header of every other operation that asks for one. It is valid for the lifetime configured on the account group, or for `valid_days` days when the group sets none.

HTTP 403. The credentials were refused: unknown email, wrong password, an unverified email or a disabled account.

Field	Type	Description
`status`	string	The literal `ok`, even though the call was refused. Do not read it on this response.
`message`	string	Human-readable detail. Never branch on it.

A refusal on this operation is the one case where the HTTP code, not the body, tells you the call failed.

Errors

400: The request body failed validation.
403: The credentials were refused. On this operation the HTTP code is the only signal: the body carries status of ok.

A refusal can also come before the operation runs: an address outside your IP allowlist, a token bound to another address, or a body that is not valid JSON. See response format and errors.

Example

Request:

curl -X POST "<API_BASE_URL>/user/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "<your dashboard email>",
    "password": "<your password>",
    "valid_days": 1
  }'

Response:

{
  "status": "ok",
  "token": "<user token>"
}