Users API

The users API is how administrators provision access to LightShip. Each user carries a username, an optional password hash, a role list, and an attribute map that policies can reference (for example user.tenant_id). All endpoints require the admin role.

POST /users

Create a user. Omit password_hash to have LightShip generate a password, return it once in the response, and set must_change_password: true so the user must change it on first sign-in.

string

required

Unique username.

string

Argon2id hash produced by lightship hash. Omit to have LightShip generate a password.

array of strings

Role names the user holds.

object

Attribute values referenced by policies, for example {"tenant_id": "acme"}.

boolean

Set to false only for non-interactive service accounts.

curl -X POST http://localhost:8080/users \
  -H "Authorization: Bearer lsk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "roles": ["booking-analyst"],
    "attributes": {"tenant_id": "acme", "user_id": "alice"}
  }'

When a password is generated, it is returned in the response exactly once. Deliver it to the user through a secure channel; LightShip never displays it again.

GET /users

List every user.

curl http://localhost:8080/users \
  -H "Authorization: Bearer lsk_xxxxxxxx"

GET /users/

Return one user, including roles and attributes.

curl http://localhost:8080/users/alice \
  -H "Authorization: Bearer lsk_xxxxxxxx"

PATCH /users/

Change roles or replace the password hash.

array of strings

Replaces the user’s role list.

string

Argon2id hash generated with lightship hash.

curl -X PATCH http://localhost:8080/users/alice \
  -H "Authorization: Bearer lsk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"roles": ["booking-analyst", "restricted-reviewer"]}'

PATCH /users//attributes

Set or remove attribute values. Pass null for a key to remove that attribute.

curl -X PATCH http://localhost:8080/users/alice/attributes \
  -H "Authorization: Bearer lsk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "acme", "old_flag": null}'

DELETE /users/

Delete a user along with their sessions and API keys. Existing tokens stop working immediately.

curl -X DELETE http://localhost:8080/users/alice \
  -H "Authorization: Bearer lsk_xxxxxxxx"

Overview

Identity

Traces

Access Model

Observability & MCP

POST /users

GET /users

GET /users/

PATCH /users/

PATCH /users//attributes

DELETE /users/

​POST /users

​GET /users

​GET /users/

​PATCH /users/

​PATCH /users//attributes

​DELETE /users/

​Related

POST /users

GET /users

GET /users/

PATCH /users/

PATCH /users//attributes

DELETE /users/

Related