Authentication

This document explains the authentication mechanisms for xPdf API endpoints.

---

Overview

Version	Auth Method	Use Case
V3	Bearer Token + xAdmin verification	Production SaaS
V2	None	Testing / Demo
V1	Internal System Token	Trusted system integration

---

V3 Authentication (Recommended)

V3 is the primary production endpoint with full authentication and usage tracking.

Request Headers

POST /api/v3/label HTTP/1.1
Host: xpdf-vector.aitrack.workers.dev
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Token Acquisition

Tokens are issued through the xAdmin dashboard. Each token is associated with:

• User account
• Usage quota
• Rate limits

Authentication Flow

┌─────────┐     ┌──────────┐     ┌────────┐
│  Client │────▶│  Worker  │────▶│ xAdmin │
└─────────┘     └──────────┘     └────────┘
     │               │                │
     │  1. Request   │                │
     │  + Token      │                │
     │──────────────▶│                │
     │               │ 2. Check Cache │
     │               │───────┐        │
     │               │       │        │
     │               │◀──────┘        │
     │               │                │
     │               │ 3. Verify      │
     │               │───────────────▶│
     │               │                │
     │               │ 4. OK/Reject   │
     │               │◀───────────────│
     │               │                │
     │  5. PDF       │                │
     │◀──────────────│                │

Cache Strategy

The Worker implements a hybrid caching strategy for performance:

1. Cache Hit (Valid): Immediately allow request, async report usage
2. Cache Miss: Synchronously verify with xAdmin
3. Blacklisted: Immediately reject (403)

Cache TTL: 5 minutes

---

V1 Authentication (Internal)

V1 is designed for trusted internal system calls.

Request Headers

POST /api/v1/label HTTP/1.1
Authorization: Bearer XADMIN_SYSTEM_TOKEN
Content-Type: application/json

The system token is configured via environment variable XADMIN_TOKEN.

---

Error Responses

401 Unauthorized

{
  "error": true,
  "code": "API-101",
  "message": "Missing Authorization header",
  "req_id": "uuid"
}

403 Forbidden

{
  "error": true,
  "code": "API-102",
  "message": "Token rejected: insufficient balance",
  "req_id": "uuid"
}

---

Best Practices

1. Store tokens securely - Never expose tokens in client-side code
2. Use environment variables - Load tokens from process.env or secrets manager
3. Handle rate limits - Implement exponential backoff on 429 responses
4. Monitor usage - Track API calls through xAdmin dashboard