User Management

Vetrix administrators can create, modify, suspend, and delete user accounts through the admin API. All endpoints require a valid admin JWT (is_admin: true).

Listing users

GET /api/v1/admin/users?q=alice&limit=50&offset=0
Authorization: Bearer <admin-jwt>

Parameter	Default	Description
q	``	Case-insensitive search on username or email
limit	50	Maximum results (max 500)
offset	0	Skip first N results (pagination)

Response:

{
  "users": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "username": "alice",
      "email": "alice@example.com",
      "display_name": "Alice",
      "is_admin": false,
      "is_active": true,
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-03-01T08:30:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Getting a single user

GET /api/v1/admin/users/{uid}

Creating a user

POST /api/v1/admin/users
Content-Type: application/json

{
  "username": "bob",
  "email": "bob@example.com",
  "display_name": "Bob Smith",
  "password": "temporarypass123",
  "is_admin": false
}

Returns 201 Created with the new user object.

Updating a user

All fields are optional. Only provided fields are updated.

PATCH /api/v1/admin/users/{uid}
Content-Type: application/json

{
  "is_active": false,
  "email": "new@example.com"
}

To suspend a user, set "is_active": false.

Deleting a user

Deleting a user revokes all their access tokens and removes them along with all their owned repositories (cascade).

DELETE /api/v1/admin/users/{uid}

Forced password reset

POST /api/v1/admin/users/{uid}/password
Content-Type: application/json

{ "password": "newtemporarypass" }

Revoking all tokens

Revokes all personal access tokens for the user. The user's JWT sessions are not affected (they expire naturally).

POST /api/v1/admin/users/{uid}/revoke-tokens

Impersonation

Admins can obtain a short-lived impersonation token to act as another user. The raw token is returned once and is not recoverable.

POST /api/v1/admin/users/{uid}/impersonate

Response:

{
  "token": "imp_...",
  "session_id": "...",
  "expires_at": "2026-04-11T18:32:00Z"
}

Impersonation sessions expire after 4 hours. To revoke all sessions for an admin → user pair:

DELETE /api/v1/admin/users/{uid}/impersonate