API Reference
Users & Tenants
Manage users, roles, and tenant configuration for your organization.
User and tenant endpoints cover account management, role assignment, and multi-tenant configuration. Only ADMIN-role users can manage other users and tenant settings.
Users Endpoints
| Method | Endpoint | Role Required | Description |
|---|---|---|---|
| GET | /users | ADMIN | List all users in tenant |
| GET | /users/:id | ADMIN | Get user details |
| POST | /users | ADMIN | Create a new user |
| PUT | /users/:id | ADMIN | Update user details or role |
| DELETE | /users/:id | ADMIN | Deactivate user account |
| GET | /users/me | Any | Get own profile |
| PUT | /users/me | Any | Update own profile |
Tenant Endpoints
| Method | Endpoint | Role Required | Description |
|---|---|---|---|
| GET | /tenants/me | ADMIN | Get current tenant settings |
| PUT | /tenants/me | ADMIN | Update tenant configuration |
| GET | /tenants/me/stats | ADMIN | Interview usage statistics |
POST /users — Create User
bash
curl -X POST http://localhost:3009/api/v1/users \
-H "Authorization: Bearer <admin-jwt>" \
-H "Content-Type: application/json" \
-d '{
"email": "recruiter@example.com",
"name": "Alex Johnson",
"role": "RECRUITER",
"password": "TempPass123!"
}'Response 201
{
"id": "user-uuid",
"email": "recruiter@example.com",
"name": "Alex Johnson",
"role": "RECRUITER",
"tenantId": "tenant-uuid",
"createdAt": "2024-01-15T10:00:00.000Z"
}| Role | Permissions |
|---|---|
| ADMIN | Full access — users, tenants, all interviews, all approvals |
| RECRUITER | Create/read/update/approve interviews within tenant |
| VIEWER | Read-only access to interviews and assessments |
GET /users/me — Own Profile
bash
curl http://localhost:3009/api/v1/users/me \
-H "Authorization: Bearer <jwt>"Response 200
{
"id": "user-uuid",
"email": "admin@demo.ai-interview.com",
"name": "Platform Admin",
"role": "ADMIN",
"tenantId": "tenant-uuid",
"mfaEnabled": false,
"lastLoginAt": "2024-01-15T09:00:00.000Z",
"createdAt": "2024-01-01T00:00:00.000Z"
}GET /tenants/me — Tenant Config
bash
curl http://localhost:3009/api/v1/tenants/me \
-H "Authorization: Bearer <admin-jwt>"Response 200
{
"id": "tenant-uuid",
"name": "Acme Corp",
"slug": "acme",
"plan": "PROFESSIONAL",
"settings": {
"maxInterviewsPerMonth": 100,
"webhookSecret": "whs_...",
"defaultInterviewDuration": 60
},
"createdAt": "2024-01-01T00:00:00.000Z"
}GET /tenants/me/stats
Usage Statistics
Response 200
{
"currentMonth": {
"interviewsCreated": 23,
"interviewsCompleted": 18,
"assessmentsApproved": 15
},
"allTime": {
"totalInterviews": 147,
"totalCandidates": 134,
"averageScore": 74.2
},
"plan": {
"limit": 100,
"used": 23,
"remaining": 77
}
}Users are strictly isolated by
tenantId. An ADMIN can only manage users within their own tenant — cross-tenant access is blocked at the RLS level.Was this page helpful?