Skip to content

Users

Users belong to an environment and are shared by every app of its group. People make their own accounts by signing up; the management API looks them up, changes their standing and their roles, and ends their sessions.

The user object:

Field Type Meaning
id uuid The sub of their tokens.
email string or null A user who logged in with a wallet, or a provider that gave no address, may have none.
email_verified boolean
phone string or null
name, picture string or null
status string active or disabled.
created_at, last_login_at string
GET/v1/environments/:id/usersviewer
Query Meaning
query Part of an email address or a name, in any case. %, _ and \ are removed from it first.
before A created_at: the page after it.
limit 50 by default, at most 200.

Newest first. total counts every user of the environment, whatever the query.

{
"users": [
{
"id": "…",
"email": "[email protected]",
"email_verified": true,
"phone": null,
"name": "Ada",
"picture": null,
"status": "active",
"created_at": "…",
"last_login_at": "…"
}
],
"total": 42,
"next_before": null
}
GET/v1/environments/:id/users/:userviewer

The user object plus:

Field Meaning
identities[] The ways they log in: { id, provider, subject, created_at, last_used_at }, such as email, google or a wallet.
sessions[] Their current sessions: { id, aal, amr, auth_time, ip, user_agent, created_at, last_seen_at, expires_at }.
roles[] { id, name }
has_password, has_totp Whether they have a password and an authenticator app.
PATCH/v1/environments/:id/users/:userdeveloper
Field Type Meaning
status string disabled or active.

Disabling ends every session of the user and their refresh tokens, and no new tokens are issued to them until they are enabled again. The user.disabled and user.enabled events go to your webhooks. The answer is the user. Any other value answers 400 “status must be active or disabled”.

To keep a user out of one app only, see an app’s users.

DELETE/v1/environments/:id/users/:userdeveloper

Deletes the account at once and for good, with its logins, second factors, sessions and tokens. In the same transaction the audit events about the user lose their address and user agent (the events stay, with the bare id), the webhook deliveries about them lose their user object, and every email to their address in the environment’s queue is deleted; see Data and retention. Answers 204, or 404, and sends user.deleted. No email goes to the user: telling them is your app’s.

On the platform environment, whose users are the developers, the answer is 409 sole_owner while the user is the only owner of a workspace, with the workspaces in workspaces; otherwise the developer leaves every workspace as when they delete their own account. A deleted account of the Seek and LinkPay environment takes the workspace made for it along, unless it has another owner.

PUT/v1/environments/:id/users/:user/rolesadmin
Field Type Meaning
role_ids uuid[] The complete set of the user’s roles, without repeats.
PUT /v1/environments/{env}/users/{user}/roles
{ "role_ids": ["…"] }
200
{ "roles": [{ "id": "…", "name": "editor" }] }

The change reaches the user’s tokens when their app next renews one (within five minutes with the default lifetimes). Each role given or taken is a role.assigned or role.removed event in the audit log.

Status code When
400 bad_request “role_ids names an unknown role” (also for a repeated id)
404 not_found Unknown user.
POST/v1/environments/:id/users/:user/revoke-sessionsdeveloper

Ends every session of the user and their refresh tokens. Access tokens already issued work until they expire.

{ "revoked": 1 }

To end one session, see Sessions.