API Docs
Users

Users API

Manage user profile and sessions. All endpoints require a JWT access token.

Get Profile

Retrieve the authenticated user's profile.

GET /users/me

Response — 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "alice@example.com",
  "name": "Alice",
  "role": "owner",
  "createdAt": "2026-04-01T10:00:00Z"
}
FieldTypeDescription
idstringUser UUID
emailstringUser email address
namestringDisplay name
rolestringServer-wide role: owner, admin, or member
createdAtstringISO 8601 account creation timestamp

Example

curl -H "Authorization: Bearer <access_token>" \
     https://vault.example.com/api/v1/users/me

Update Profile

Update the authenticated user's display name.

PUT /users/me

Request

{
  "name": "Alice Smith"
}
FieldTypeRequiredDescription
namestringyesNew display name

Response — 200 OK

Returns the full updated profile (same shape as Get Profile).

Errors

  • 400 INVALID -- Validation failed (empty name)

Example

curl -X PUT https://vault.example.com/api/v1/users/me \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice Smith"}'

List Sessions

Retrieve all active sessions for the authenticated user.

GET /users/me/sessions

Response — 200 OK

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "deviceName": "Chrome on macOS",
    "ipAddress": "203.0.113.42",
    "createdAt": "2026-04-01T10:00:00Z",
    "lastActiveAt": "2026-04-09T08:30:00Z"
  }
]
FieldTypeDescription
idstringSession UUID
deviceNamestringDevice name provided at login
ipAddressstringIP address of the session
createdAtstringSession creation timestamp
lastActiveAtstringLast activity timestamp

Example

curl -H "Authorization: Bearer <access_token>" \
     https://vault.example.com/api/v1/users/me/sessions

Revoke Session

Revoke a specific session, logging that device out.

DELETE /users/me/sessions/:sessionId

Response — 204 No Content

No response body.

Errors

  • 404 NOT_FOUND -- Session not found or does not belong to user

Example

curl -X DELETE -H "Authorization: Bearer <access_token>" \
     https://vault.example.com/api/v1/users/me/sessions/a1b2c3d4-...

Revoking a session invalidates its refresh token. The access token remains valid until it expires (short-lived), but cannot be refreshed.

TOTP (2FA)Organizations