Admin API Endpoints

This document describes the admin-specific API endpoints for the Candivista platform.

Authentication

All admin endpoints require authentication with a valid JWT token from a user with role: 'admin'.

Headers:

Authorization: Bearer <jwt_token>
Content-Type: application/json

Base URL

http://localhost:8083/rest/admin

Endpoints

System Statistics

GET /statistics

Get system-wide statistics and metrics.

Response:

{
  "total_users": 150,
  "active_users": 142,
  "total_jobs": 89,
  "total_interviews": 234,
  "total_tokens_purchased": 1250,
  "total_tokens_used": 890,
  "total_revenue": 12500.00,
  "generated_at": "2024-01-15T10:30:00Z"
}

User Management

GET /users

Get all users in the system.

Response:

[
  {
    "id": "user-uuid",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "role": "recruiter",
    "company_name": "Tech Corp",
    "is_active": true,
    "last_login_at": "2024-01-15T09:00:00Z",
    "created_at": "2024-01-01T00:00:00Z"
  }
]

GET /users/:id

Get a specific user by ID.

PUT /users/:id

Update user information.

Request Body:

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "role": "recruiter",
  "company_name": "Tech Corp",
  "is_active": true
}

PATCH /users/:id/toggle-status

Toggle user active/inactive status.

Response:

{
  "success": true,
  "new_status": false
}

PATCH /users/:id/password

Change user password.

Request Body:

{
  "new_password": "newpassword123"
}

POST /users

Create a new user.

Request Body:

{
  "email": "newuser@example.com",
  "password": "password123",
  "first_name": "Jane",
  "last_name": "Smith",
  "role": "recruiter",
  "company_name": "Startup Inc"
}

Job Management

GET /jobs

Get all jobs in the system with user information.

Response:

[
  {
    "id": "job-uuid",
    "user_id": "user-uuid",
    "title": "Senior Developer",
    "description": "Job description...",
    "status": "active",
    "created_at": "2024-01-15T10:00:00Z",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "company_name": "Tech Corp"
  }
]

GET /jobs/:id

Get a specific job by ID.

PATCH /jobs/:id/status

Update job status.

Request Body:

{
  "status": "paused"
}

PUT /jobs/:id

Update job information.

Request Body:

{
  "title": "Updated Job Title",
  "description": "Updated description...",
  "status": "active"
}

Token Management

GET /user-token-summaries

Get token usage summaries for all users.

Response:

[
  {
    "user_id": "user-uuid",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "total_purchased": 50,
    "total_used": 25,
    "total_available": 25,
    "utilization_percentage": 50.0
  }
]

POST /add-tokens

Add tokens to a specific user.

Request Body:

{
  "user_id": "user-uuid",
  "quantity": 10,
  "price_per_token": 5.00,
  "total_price": 50.00
}

Token Packages

GET /token-packages

Get all token packages.

Response:

[
  {
    "id": "package-uuid",
    "name": "Professional Pack",
    "description": "Ideal for regular recruiters",
    "quantity": 20,
    "price_per_token": 4.00,
    "total_price": 80.00,
    "discount_percentage": 20,
    "is_popular": true,
    "is_active": true
  }
]

POST /token-packages

Create a new token package.

Request Body:

{
  "name": "New Package",
  "description": "Package description",
  "quantity": 10,
  "price_per_token": 4.50,
  "total_price": 45.00,
  "discount_percentage": 10,
  "is_popular": false,
  "is_active": true
}

PUT /token-packages/:id

Update a token package.

PATCH /token-packages/:id/toggle-status

Toggle package active/inactive status.

DELETE /token-packages/:id

Delete a token package.

Interview Management

GET /interviews

Get all interviews in the system.

GET /interviews/:id

Get a specific interview by ID.

Payment Records

GET /payments

Get all payment records.

GET /payments/:id

Get a specific payment record by ID.

Error Responses

All endpoints return appropriate HTTP status codes and error messages:

  • 400 Bad Request - Invalid request data
  • 401 Unauthorized - Invalid or missing authentication
  • 403 Forbidden - Insufficient permissions (non-admin user)
  • 404 Not Found - Resource not found
  • 500 Internal Server Error - Server error

Error Response Format:

{
  "message": "Error description",
  "status": 400
}

Testing

Use the provided test script to verify admin endpoints:

node test-admin.js

Security Notes

  1. All admin endpoints require admin role verification
  2. JWT tokens are validated on every request
  3. User passwords are hashed using bcrypt
  4. All database queries use parameterized statements to prevent SQL injection
  5. Admin actions are logged for audit purposes

Database Schema

The admin endpoints interact with the following database tables:

  • users - User accounts and profiles
  • jobs - Job postings
  • interview_tokens - Token purchases and usage
  • token_packages - Available token packages
  • interviews - Interview sessions
  • payment_records - Payment history
  • user_usage - Usage tracking and limits