admin be

[nikhilgosavi-josh]

EZScreen Admin BE APIs — Request & Response
Branch: feat/admin-be
Base URL: /api/v1
Auth: Authorization: Bearer <access_token>
Refresh cookie: ezscreen_refresh (httpOnly, path=/api/v1/auth)

================================================================================
AUTH
POST /api/v1/auth/login
Auth: none
Notes:
Platform / shared login. Any active user (including super_admin) may use this.
Organization workspace portal should use POST /auth/org/login instead.
Request:
{
"email": "admin@ezscreen.io",
"password": "your-password"
}

Response 200:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer",
"expires_in": 3600,
"user": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"organization_id": null,
"role": "super_admin",
"email": "admin@ezscreen.io",
"first_name": "Platform",
"last_name": "Admin",
"phone": null,
"status": "active"
}
}
Also sets cookie: ezscreen_refresh

Response 401:
{
"detail": "Invalid email or password"
}

POST /api/v1/auth/org/login
Auth: none
Notes:
Organization workspace login. Allows organization_admin and hr only.
User must be active. organization_id is required. Linked org must exist
and is_active === true.
Request:
{
"email": "admin@acme.com",
"password": "your-password"
}

Response 200:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer",
"expires_in": 3600,
"user": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"organization_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"role": "organization_admin",
"email": "admin@acme.com",
"first_name": "Jane",
"last_name": "Doe",
"phone": null,
"status": "active"
}
}
Also sets cookie: ezscreen_refresh

Response 401:
{
"detail": "Invalid email or password"
}

Response 403 (wrong role, e.g. super_admin or candidate):
{
"detail": "Organization workspace access only"
}

Response 403 (org missing):
{
"detail": "Organization not found"
}

Response 403 (org suspended):
{
"detail": "Organization is suspended"
}

POST /api/v1/auth/refresh
Auth: refresh cookie only
Request: (no body)

Response 200:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer",
"expires_in": 3600
}
Also rotates cookie: ezscreen_refresh

Response 401:
{
"detail": "Refresh token missing"
}

Response 401 (already rotated / logged out):
{
"detail": "Refresh token revoked"
}

GET /api/v1/auth/me
Auth: Bearer
Request: (no body)

Response 200:
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"organization_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"role": "organization_admin",
"email": "admin@acme.com",
"first_name": "Jane",
"last_name": "Doe",
"phone": null,
"status": "active"
}

POST /api/v1/auth/logout
Auth: Bearer
Request:
{}

Response 200:
{
"message": "Successfully logged out"
}
Also clears cookie: ezscreen_refresh

GET /api/v1/auth/org/check
Auth: Bearer (organization_admin or hr)
Request: (no body)

Response 200:
{
"message": "Organization workspace access confirmed"
}

Response 403:
{
"detail": "Insufficient permissions"
}

GET /api/v1/auth/super-admin/check
Auth: Bearer (super_admin only)
Request: (no body)

Response 200:
{
"message": "Super admin access confirmed"
}

Response 403:
{
"detail": "Insufficient permissions"
}

================================================================================
ORGANIZATIONS
GET /api/v1/organizations
Auth: Bearer (super_admin)
Query: page=1&limit=20&q=acme&status=active
Notes:
status = active | suspended | all
Request: (no body)

Response 200:
[
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Acme Corp",
"domain": "acme",
"logo_url": null,
"is_active": true,
"created_at": "2026-08-12T10:00:00+00:00",
"user_count": 3,
"job_count": 12,
"application_count": 45
}
]

POST /api/v1/organizations
Auth: Bearer (super_admin)
Request:
{
"name": "Acme Corp",
"domain": "acme",
"logo_url": "https://cdn.example.com/acme.png"
}

Response 201:
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Acme Corp",
"domain": "acme",
"logo_url": "https://cdn.example.com/acme.png",
"is_active": true,
"created_at": "2026-08-12T10:00:00+00:00",
"user_count": 0,
"job_count": 0,
"application_count": 0
}

Response 409:
{
"detail": "An organization with this domain already exists"
}

GET /api/v1/organizations/{organization_id}
Auth: Bearer (super_admin, organization_admin own org, hr own org)
Request: (no body)

Response 200:
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Acme Corp",
"domain": "acme",
"logo_url": null,
"is_active": true,
"created_at": "2026-08-12T10:00:00+00:00",
"user_count": 3,
"job_count": 12,
"application_count": 45
}

Response 403 (other org):
{
"detail": "Cannot access another organization"
}

Response 404:
{
"detail": "Organization not found"
}

PUT /api/v1/organizations/{organization_id}
Auth: Bearer (super_admin or organization_admin for own org)
Notes:
All fields optional.
Only super_admin may set is_active to false (suspend).
Request:
{
"name": "Acme Corporation",
"domain": "acme-corp",
"logo_url": "https://cdn.example.com/new-logo.png",
"is_active": true
}

Response 200:
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Acme Corporation",
"domain": "acme-corp",
"logo_url": "https://cdn.example.com/new-logo.png",
"is_active": true,
"created_at": "2026-08-12T10:00:00+00:00",
"user_count": 3,
"job_count": 12,
"application_count": 45
}

Response 403 (org_admin trying to suspend):
{
"detail": "Only super_admin can suspend organizations"
}

DELETE /api/v1/organizations/{organization_id}
Auth: Bearer (super_admin)
Request: (no body)

Response 200:
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"is_active": false,
"message": "Organization deactivated"
}

GET /api/v1/organizations/{organization_id}/users
Auth: Bearer (super_admin or organization_admin for own org)
Request: (no body)

Response 200:
[
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"organization_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"role": "organization_admin",
"email": "admin@acme.com",
"first_name": "Jane",
"last_name": "Doe",
"phone": null,
"status": "active",
"temporary_password": null
}
]

POST /api/v1/organizations/{organization_id}/users
Auth: Bearer (super_admin or organization_admin for own org)
Request:
{
"email": "hr@acme.com",
"password": "OptionalMin8Chars",
"first_name": "Jane",
"last_name": "Doe",
"phone": "+91-9876543210",
"role": "hr"
}

Notes:
password is optional (min 8 if provided). If omitted, server auto-generates one.
role must be organization_admin or hr (default: organization_admin).
super_admin and organization_admin (own org) may provision both roles.
Cannot provision users for a suspended organization.

Response 201:
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"organization_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"role": "hr",
"email": "hr@acme.com",
"first_name": "Jane",
"last_name": "Doe",
"phone": "+91-9876543210",
"status": "active",
"temporary_password": "xK9#mP2qL8nR"
}

Note: temporary_password is set only when password was auto-generated.

Response 400:
{
"detail": "Cannot provision users for a suspended organization"
}

Response 409:
{
"detail": "A user with this email already exists"
}

================================================================================
SYSTEM
GET /api/v1/system/health
Auth: none
Request: (no body)

Response 200:
{
"status": "healthy",
"service": "core-api",
"database_url_configured": true,
"jwt_configured": true
}

GET /api/v1/system/health/detailed
Auth: Bearer (super_admin)
Request: (no body)

Response 200:
{
"status": "healthy",
"service": "core-api",
"database": {
"name": "PostgreSQL",
"detail": "primary database",
"status": "healthy"
},
"api": {
"name": "API gateway",
"detail": "core-api local",
"status": "healthy"
},
"parse_workers": {
"name": "Parse workers (JD / resume)",
"detail": "Workers and Attendee bot are not deployed yet — shown as pending/healthy stub.",
"status": "healthy"
},
"screening_bot": {
"name": "Screening bot dispatch",
"detail": "Attendee integration not configured",
"status": "degraded"
},
"object_storage": {
"name": "Object storage (S3)",
"detail": "MinIO / S3 not required for platform ops API",
"status": "healthy"
},
"stats": {
"organizations": 5,
"users": 42,
"jobs": 18,
"applications": 120,
"uptime_seconds": 8642,
"jwt_ttl_minutes": 60
},
"recent_events": [
{
"time": "14:30",
"message": "Health check · 5 orgs · 42 users"
},
{
"time": "12:00",
"message": "Core API process started"
}
]
}

GET /api/v1/system/settings
Auth: Bearer (super_admin)
Request: (no body)

Response 200:
{
"platform_name": "EZScreen",
"support_email": "support@ezscreen.io",
"timezone": "Asia/Kolkata",
"extraction_model": "gemma-parse-v2",
"screening_model": "gemma-screen-v3",
"auto_retry_failed_jobs": true,
"require_mfa_super_admin": true,
"invite_expiry_days": 7
}

PUT /api/v1/system/settings
Auth: Bearer (super_admin)
Request (all fields optional):
{
"platform_name": "EZScreen",
"support_email": "support@ezscreen.io",
"timezone": "UTC",
"extraction_model": "gemma-parse-v2",
"screening_model": "gemma-screen-v3",
"auto_retry_failed_jobs": true,
"require_mfa_super_admin": false,
"invite_expiry_days": 14
}

Response 200:
{
"platform_name": "EZScreen",
"support_email": "support@ezscreen.io",
"timezone": "UTC",
"extraction_model": "gemma-parse-v2",
"screening_model": "gemma-screen-v3",
"auto_retry_failed_jobs": true,
"require_mfa_super_admin": false,
"invite_expiry_days": 14
}