Users API

Endpoints for user management. All endpoints require a valid user session.

Get Current User

GET /v1/users/me

Authentication: User session (Bearer)

Response 200 OK

{
  "id": "user_abc123",
  "email": "dev@example.com",
  "display_name": "Jane Developer",
  "role": "developer",
  "status": "active",
  "avatar_url": "https://lh3.googleusercontent.com/...",
  "created_at": 1738800000,
  "updated_at": 1738800000
}

---

List Users

GET /v1/users

Authentication: User session (Bearer, owner/admin)

Response 200 OK

Returns an array of user objects.

---

Invite User

POST /v1/users/invite

Authentication: User session (Bearer, owner/admin)

Request body

{
  "email": "dev@example.com",
  "role": "developer"
}

Field	Type	Required	Description
email	string	Yes	Email address (must match OIDC provider account)
role	string	Yes	Role to assign: admin, developer, or qa_viewer

Response 200 OK

Returns the created user object with invited status.

Error responses

Status	Code	Description
400	invalid_input	Invalid email or role
403	forbidden	Insufficient permissions
409	already_exists	User with this email already exists

---

Update User Role

PATCH /v1/users/{user_id}/role

Authentication: User session (Bearer, owner/admin)

Request body

{
  "role": "admin"
}

Field	Type	Required	Description
role	string	Yes	New role: admin, developer, or qa_viewer

Response 200 OK

Returns the updated user object.

Error responses

Status	Code	Description
400	invalid_input	Invalid role value
403	forbidden	Insufficient permissions
404	not_found	User not found

---

Transfer Owner

POST /v1/users/transfer-owner

Authentication: User session (Bearer, owner)

Transfers the singleton owner role to an existing active user. The previous owner becomes admin, the instance owner record is updated, and sessions for both affected users are revoked.

Request body

{
  "email": "new-owner@example.com"
}

Field	Type	Required	Description
email	string	Yes	Active user who should become the new owner

Response 200 OK

{
  "previous_owner": {
    "id": "user_old",
    "email": "owner@example.com",
    "role": "admin",
    "status": "active",
    "created_at": 1738800000,
    "updated_at": 1738800000
  },
  "owner": {
    "id": "user_new",
    "email": "new-owner@example.com",
    "role": "owner",
    "status": "active",
    "created_at": 1738800100,
    "updated_at": 1738800200
  }
}

Error responses

Status	Code	Description
400	invalid_email	Invalid target email
403	forbidden	Caller is not the owner
404	user_not_found	Target user does not exist
409	user_not_active	Target user has not signed in yet or is disabled

---

Disable User

Disable a user account. The user's sessions are invalidated and they cannot sign in.

DELETE /v1/users/{user_id}

Authentication: User session (Bearer, owner/admin)

Response 200 OK

Returns the updated user object with disabled status.

Error responses

Status	Code	Description
403	forbidden	Insufficient permissions
404	not_found	User not found

INFO

This endpoint disables the user rather than permanently deleting them. User records are preserved for the audit trail.

---

Re-enable User

Re-enable a previously disabled user account.

POST /v1/users/{user_id}/enable

Authentication: User session (Bearer, owner/admin)

Response 200 OK

Returns the updated user object with active status.

Error responses

Status	Code	Description
403	forbidden	Insufficient permissions
404	not_found	User not found