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>"

const response = await fetch('https://api.horsetrust.com/api/admin/dashboard', {
  headers: {
    'Authorization': `Bearer ${adminToken}`
  }
});
const data = await response.json();

import requests

response = requests.get(
    'https://api.horsetrust.com/api/admin/dashboard',
    headers={'Authorization': f'Bearer {admin_token}'}
)
data = response.json()

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

Response

boolean

required

Indicates request success

object

required

number

Total registered users across all roles

number

Number of sellers awaiting verification

number

Total horses listed on the platform

number

Number of horses with status “active”

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>"

const response = await fetch('https://api.horsetrust.com/api/admin/sellers/pending', {
  headers: {
    'Authorization': `Bearer ${adminToken}`
  }
});
const sellers = await response.json();

import requests

response = requests.get(
    'https://api.horsetrust.com/api/admin/sellers/pending',
    headers={'Authorization': f'Bearer {admin_token}'}
)
sellers = response.json()

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

Response

boolean

required

Indicates request success

array

required

Array of seller objects awaiting verification

string

Seller’s email address

string

Seller’s full name

string

Seller’s phone number

object

string

Current status (will be “pending”)

string

Business name if applicable

number

Years of horse trading experience

string

Account creation timestamp

Example Response

{
  "success": true,
  "data": [
    {
      "_id": "60d5f7e8f8d9a72e3c8b4567",
      "email": "john.smith@example.com",
      "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"
  }'

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

// Approve seller
const response = await fetch(
  `https://api.horsetrust.com/api/admin/sellers/${sellerId}/verify`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${adminToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      action: 'approve'
    })
  }
);

// Reject seller
const response = await fetch(
  `https://api.horsetrust.com/api/admin/sellers/${sellerId}/verify`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${adminToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      action: 'reject',
      rejection_reason: 'Insufficient documentation provided'
    })
  }
);

import requests

# Approve seller
response = requests.put(
    f'https://api.horsetrust.com/api/admin/sellers/{seller_id}/verify',
    headers={
        'Authorization': f'Bearer {admin_token}',
        'Content-Type': 'application/json'
    },
    json={'action': 'approve'}
)

# Reject seller
response = requests.put(
    f'https://api.horsetrust.com/api/admin/sellers/{seller_id}/verify',
    headers={
        'Authorization': f'Bearer {admin_token}',
        'Content-Type': 'application/json'
    },
    json={
        'action': 'reject',
        'rejection_reason': 'Insufficient documentation provided'
    }
)

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

string

required

Action to perform: "approve" or "reject"

string

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

Response

boolean

required

Indicates request success

string

required

Human-readable result message

object

required

Updated seller user object (password excluded)

object

string

Updated status: “verified” or “rejected”

boolean

True if approved, false if rejected

string

Set to “manual” when approved by admin

string

Timestamp of verification (approve only)

string

Admin user ID who performed verification

string

Reason for rejection (reject only)

Example Response (Approved)

{
  "success": true,
  "message": "Seller verified",
  "data": {
    "_id": "60d5f7e8f8d9a72e3c8b4567",
    "email": "john.smith@example.com",
    "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": "john.smith@example.com",
    "full_name": "John Smith",
    "role": "seller",
    "seller_profile": {
      "verification_status": "rejected",
      "is_verified_badge": false,
      "rejection_reason": "Insufficient documentation provided"
    }
  }
}

Error Responses

Invalid seller ID or action parameter

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

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>"

const response = await fetch('https://api.horsetrust.com/api/admin/vet-records/pending', {
  headers: {
    'Authorization': `Bearer ${adminToken}`
  }
});
const records = await response.json();

import requests

response = requests.get(
    'https://api.horsetrust.com/api/admin/vet-records/pending',
    headers={'Authorization': f'Bearer {admin_token}'}
)
records = response.json()

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

Response

boolean

required

Indicates request success

array

required

Array of pending vet records with populated horse information

string

Vet record ID

object

Populated horse object

string

Horse ID

string

Horse name

string

Horse breed

string

Owner/seller ID

string

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

string

URL to uploaded veterinary document

string

Current status (will be “pending”)

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"
  }'

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": "reject",
    "rejection_reason": "Document appears to be expired"
  }'

// Validate record
const response = await fetch(
  `https://api.horsetrust.com/api/admin/vet-records/${recordId}/validate`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${adminToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      action: 'validate'
    })
  }
);

// Reject record
const response = await fetch(
  `https://api.horsetrust.com/api/admin/vet-records/${recordId}/validate`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${adminToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      action: 'reject',
      rejection_reason: 'Document appears to be expired'
    })
  }
);

import requests

# Validate record
response = requests.put(
    f'https://api.horsetrust.com/api/admin/vet-records/{record_id}/validate',
    headers={
        'Authorization': f'Bearer {admin_token}',
        'Content-Type': 'application/json'
    },
    json={'action': 'validate'}
)

# Reject record
response = requests.put(
    f'https://api.horsetrust.com/api/admin/vet-records/{record_id}/validate',
    headers={
        'Authorization': f'Bearer {admin_token}',
        'Content-Type': 'application/json'
    },
    json={
        'action': 'reject',
        'rejection_reason': 'Document appears to be expired'
    }
)

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

string

required

Action to perform: "validate" or "reject"

string

Required when action is “reject”. Reason for rejection

Response

boolean

required

Indicates request success

object

required

Updated vet record object

string

Updated status: “validated” or “rejected”

string

Admin user ID who performed validation (validate only)

string

Timestamp of validation (validate only)

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

Invalid action parameter

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

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>"

const response = await fetch(
  `https://api.horsetrust.com/api/admin/horses/${horseId}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${adminToken}`
    }
  }
);
const result = await response.json();

import requests

response = requests.delete(
    f'https://api.horsetrust.com/api/admin/horses/{horse_id}',
    headers={'Authorization': f'Bearer {admin_token}'}
)
result = response.json()

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

boolean

required

Indicates request success

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

​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

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