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 |
List users
Section titled “List users”| 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_verified": true, "phone": null, "name": "Ada", "picture": null, "status": "active", "created_at": "…", "last_login_at": "…" } ], "total": 42, "next_before": null}Read a user
Section titled “Read a user”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. |
Disable or enable a user
Section titled “Disable or enable a user”| 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 a user
Section titled “Delete a user”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.
Set a user’s roles
Section titled “Set a user’s roles”| 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. |
End a user’s sessions
Section titled “End a user’s sessions”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.