Admin API - Horse Trust

Overview

The Admin API provides privileged endpoints for platform administrators to manage seller verifications, validate veterinary records, monitor platform statistics, and moderate content.

All admin endpoints require both authentication and admin role authorization. Requests without valid admin credentials will be rejected with a 403 Forbidden response.

Authentication & Authorization

Admin endpoints use two-layer protection:

Authentication: Valid JWT token in Authorization: Bearer <token> header
Authorization: User must have role: "admin" in their account

# All requests must include authentication header
Authorization: Bearer <admin_jwt_token>

Access Control

Admin routes are protected by two middleware functions (server/src/routes/admin.ts:11):

authenticate - Validates JWT token and loads user context
requireAdmin - Verifies user has admin role

Unauthorized requests receive:

{
  "success": false,
  "message": "Access denied"
}

Get Admin Dashboard

curl -X GET https://api.horsetrust.com/api/admin/dashboard \
  -H "Authorization: Bearer <admin_token>"

Retrieves platform-wide statistics for the admin dashboard. Endpoint: GET /api/admin/dashboard

Response

success

boolean

required

Indicates request success

data

object

required

totalUsers

number

Total registered users across all roles

pendingSellers

number

Number of sellers awaiting verification

totalHorses

number

Total horses listed on the platform

activeListings

number

Number of horses with status “active”

pendingVet

number

Veterinary records awaiting validation

Example Response

{
  "success": true,
  "data": {
    "totalUsers": 1247,
    "pendingSellers": 8,
    "totalHorses": 543,
    "activeListings": 412,
    "pendingVet": 23
  }
}

Get Pending Sellers

curl -X GET https://api.horsetrust.com/api/admin/sellers/pending \
  -H "Authorization: Bearer <admin_token>"

Retrieves all sellers with pending verification status for admin review. Endpoint: GET /api/admin/sellers/pending

Response

success

boolean

required

Indicates request success

data

array

required

Array of seller objects awaiting verification

string

Seller’s email address

full_name

string

Seller’s full name

phone

string

Seller’s phone number

seller_profile

object

verification_status

string

Current status (will be “pending”)

business_name

string

Business name if applicable

years_experience

number

Years of horse trading experience

created_at

string

Account creation timestamp

Example Response

{
  "success": true,
  "data": [
    {
      "_id": "60d5f7e8f8d9a72e3c8b4567",
      "email": "[email protected]",
      "full_name": "John Smith",
      "phone": "+1234567890",
      "seller_profile": {
        "verification_status": "pending",
        "business_name": "Smith Stables",
        "years_experience": 15
      },
      "created_at": "2024-03-01T10:30:00.000Z"
    }
  ]
}

Verify Seller

curl -X PUT https://api.horsetrust.com/api/admin/sellers/60d5f7e8f8d9a72e3c8b4567/verify \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "approve"
  }'

Approve or reject a seller’s verification request. Endpoint: PUT /api/admin/sellers/:id/verify

Path Parameters

string

required

Seller’s user ID (MongoDB ObjectId)

Body Parameters

action

string

required

Action to perform: "approve" or "reject"

rejection_reason

string

Required when action is “reject”. Reason for rejection shown to seller

Response

success

boolean

required

Indicates request success

message

string

required

Human-readable result message

data

object

required

Updated seller user object (password excluded)

seller_profile

object

verification_status

string

Updated status: “verified” or “rejected”

is_verified_badge

boolean

True if approved, false if rejected

verification_method

string

Set to “manual” when approved by admin

verified_at

string

Timestamp of verification (approve only)

verified_by

string

Admin user ID who performed verification

rejection_reason

string

Reason for rejection (reject only)

Example Response (Approved)

{
  "success": true,
  "message": "Seller verified",
  "data": {
    "_id": "60d5f7e8f8d9a72e3c8b4567",
    "email": "[email protected]",
    "full_name": "John Smith",
    "role": "seller",
    "seller_profile": {
      "verification_status": "verified",
      "is_verified_badge": true,
      "verification_method": "manual",
      "verified_at": "2024-03-05T14:30:00.000Z",
      "verified_by": "60d5f7e8f8d9a72e3c8b1234",
      "rejection_reason": null
    }
  }
}

Example Response (Rejected)

{
  "success": true,
  "message": "Seller rejected",
  "data": {
    "_id": "60d5f7e8f8d9a72e3c8b4567",
    "email": "[email protected]",
    "full_name": "John Smith",
    "role": "seller",
    "seller_profile": {
      "verification_status": "rejected",
      "is_verified_badge": false,
      "rejection_reason": "Insufficient documentation provided"
    }
  }
}

Error Responses

400 Bad Request

Invalid seller ID or action parameter

{
  "success": false,
  "message": "action must be 'approve' or 'reject'"
}

404 Not Found

Seller not found

{
  "success": false,
  "message": "Seller not found"
}

Get Pending Vet Records

curl -X GET https://api.horsetrust.com/api/admin/vet-records/pending \
  -H "Authorization: Bearer <admin_token>"

Retrieves all veterinary records awaiting validation, sorted by creation date (oldest first). Endpoint: GET /api/admin/vet-records/pending

Response

success

boolean

required

Indicates request success

data

array

required

Array of pending vet records with populated horse information

_id

string

Vet record ID

horse_id

object

Populated horse object

_id

string

Horse ID

name

string

Horse name

breed

string

Horse breed

seller_id

string

Owner/seller ID

record_type

string

Type of record (e.g., “vaccination”, “health_check”)

document_url

string

URL to uploaded veterinary document

validation_status

string

Current status (will be “pending”)

created_at

string

Record creation timestamp

Example Response

{
  "success": true,
  "data": [
    {
      "_id": "60d5f7e8f8d9a72e3c8b9999",
      "horse_id": {
        "_id": "60d5f7e8f8d9a72e3c8b8888",
        "name": "Thunder",
        "breed": "Thoroughbred",
        "seller_id": "60d5f7e8f8d9a72e3c8b4567"
      },
      "record_type": "vaccination",
      "document_url": "https://storage.horsetrust.com/vet-docs/abc123.pdf",
      "validation_status": "pending",
      "notes": "Annual vaccination record",
      "created_at": "2024-02-28T09:15:00.000Z"
    }
  ]
}

Validate Vet Record

curl -X PUT https://api.horsetrust.com/api/admin/vet-records/60d5f7e8f8d9a72e3c8b9999/validate \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "validate"
  }'

Validate or reject a veterinary record submission. Endpoint: PUT /api/admin/vet-records/:id/validate

Path Parameters

string

required

Vet record ID (MongoDB ObjectId)

Body Parameters

action

string

required

Action to perform: "validate" or "reject"

rejection_reason

string

Required when action is “reject”. Reason for rejection

Response

success

boolean

required

Indicates request success

data

object

required

Updated vet record object

validation_status

string

Updated status: “validated” or “rejected”

validated_by

string

Admin user ID who performed validation (validate only)

validated_at

string

Timestamp of validation (validate only)

rejection_reason

string

Reason for rejection (reject only)

Example Response (Validated)

{
  "success": true,
  "data": {
    "_id": "60d5f7e8f8d9a72e3c8b9999",
    "horse_id": "60d5f7e8f8d9a72e3c8b8888",
    "record_type": "vaccination",
    "document_url": "https://storage.horsetrust.com/vet-docs/abc123.pdf",
    "validation_status": "validated",
    "validated_by": "60d5f7e8f8d9a72e3c8b1234",
    "validated_at": "2024-03-05T14:45:00.000Z",
    "rejection_reason": null
  }
}

Example Response (Rejected)

{
  "success": true,
  "data": {
    "_id": "60d5f7e8f8d9a72e3c8b9999",
    "horse_id": "60d5f7e8f8d9a72e3c8b8888",
    "record_type": "vaccination",
    "document_url": "https://storage.horsetrust.com/vet-docs/abc123.pdf",
    "validation_status": "rejected",
    "rejection_reason": "Document appears to be expired"
  }
}

Error Responses

400 Bad Request

Invalid action parameter

{
  "success": false,
  "message": "action must be 'validate' or 'reject'"
}

404 Not Found

Vet record not found

{
  "success": false,
  "message": "Vet record not found"
}

Delete Horse Listing

curl -X DELETE https://api.horsetrust.com/api/admin/horses/60d5f7e8f8d9a72e3c8b8888 \
  -H "Authorization: Bearer <admin_token>"

Permanently delete a horse listing and all associated veterinary records. This is a destructive operation that cannot be undone. Endpoint: DELETE /api/admin/horses/:id

This performs a hard delete, removing the horse listing and all related vet records from the database permanently. Use with caution.

Path Parameters

string

required

Horse listing ID (MongoDB ObjectId)

Response

success

boolean

required

Indicates request success

message

string

required

Confirmation message

Example Response

{
  "success": true,
  "message": "Listing deleted by admin"
}

Use Cases

Remove fraudulent or inappropriate listings
Delete duplicate entries
Remove horses that violate platform policies
Clean up test data

Error Handling

All admin endpoints follow consistent error response patterns:

401 Unauthorized

Missing or invalid authentication token:

{
  "success": false,
  "message": "Authentication required"
}

403 Forbidden

Valid user but not an admin:

{
  "success": false,
  "message": "Access denied"
}

500 Server Error

Internal server error:

{
  "success": false,
  "message": "Server error"
}

Security Best Practices

Admin Token Security

Store admin tokens securely (never in client-side code)
Use environment variables for token storage
Implement token rotation policies
Log all admin actions for audit trails

Action Verification

Verify seller/record details before approval/rejection
Provide clear rejection reasons for transparency
Review documents thoroughly before validation
Confirm destructive operations (deletes) before execution

Access Monitoring

Monitor admin API usage patterns
Set up alerts for unusual activity
Regular audit of admin account access
Implement rate limiting for admin endpoints

User Management

View and manage user accounts

Horse Listings

Browse and manage horse listings

Vet Records

Public vet record endpoints

Authentication

User and admin authentication

Authentication

Horses

Chat

Admin

​Overview

​Authentication & Authorization

​Access Control

​Get Admin Dashboard

​Response

​Example Response

​Get Pending Sellers

​Response

​Example Response

​Verify Seller

​Path Parameters

​Body Parameters

​Response

​Example Response (Approved)

​Example Response (Rejected)

​Error Responses

​Get Pending Vet Records

​Response

​Example Response

​Validate Vet Record

​Path Parameters

​Body Parameters

​Response

​Example Response (Validated)

​Example Response (Rejected)

​Error Responses

​Delete Horse Listing

​Path Parameters

​Response

​Example Response

​Use Cases

​Error Handling

​401 Unauthorized

​403 Forbidden

​500 Server Error

​Security Best Practices

Admin Token Security

Action Verification

Access Monitoring

​Related Endpoints

User Management

Horse Listings

Vet Records

Authentication

Build docs developers (and LLMs) love

Overview

Authentication & Authorization

Access Control

Get Admin Dashboard

Response

Example Response

Get Pending Sellers

Response

Example Response

Verify Seller

Path Parameters

Body Parameters

Response

Example Response (Approved)

Example Response (Rejected)

Error Responses

Get Pending Vet Records

Response

Example Response

Validate Vet Record

Path Parameters

Body Parameters

Response

Example Response (Validated)

Example Response (Rejected)

Error Responses

Delete Horse Listing

Path Parameters

Response

Example Response

Use Cases

Error Handling

401 Unauthorized

403 Forbidden

500 Server Error

Security Best Practices

Related Endpoints