AIProxy
Home
Login
EN
中文
日本語
ES
FR
한국어
DE
# AIProxy Gateway API Specifications & Security Architecture This document outlines all public, admin, and portal HTTP/HTTPS endpoints exposed by the AIProxy gateway and details the defensive security layers implemented to protect the infrastructure. --- ## 1. API Specifications ### Public client APIs #### A. Chat Completions (OpenAI Compatible) * **Route**: `POST /v1/chat/completions` * **Authentication**: `Authorization: Bearer <API_KEY>` or HMAC Signature headers. * **Request Format**: JSON payload resembling OpenAI chat completion standard. ```json { "model": "auto", "messages": [ {"role": "user", "content": "Hello"} ], "stream": false } ``` * **Response Format**: OpenAI-compatible JSON or text/event-stream. #### B. Messages (Anthropic Compatible) * **Route**: `POST /v1/messages` * **Authentication**: `X-API-Key: <API_KEY>` or HMAC Signature headers. * **Request Format**: JSON payload resembling Anthropic messages standard. * **Response Format**: Anthropic-compatible JSON. #### C. Balance Check & Device Registration * **Route**: `GET/POST /v1/balance` * **Authentication**: `Authorization: Bearer <API_KEY>` or HMAC Signature headers. * **Response Format**: JSON ```json { "api_key": "UUID", "balance": 15.50, "email": "UUID@device.local", "rate_limit_burst": 5, "rate_limit_rpm": 20, "role": "device" } ``` --- ### Portal & Top-up APIs #### A. Portal UI * **Route**: `GET /portal` * **Access**: Open to users. Allows query param `?api_key=UUID` for automatic login. #### B. Portal Login * **Route**: `POST /api/portal/login` * **Payload**: `{"api_key": "sk-aiproxy-..."}` * **Response**: JSON User details. #### C. Create Stripe Payment Intent * **Route**: `POST /api/portal/create-payment-intent` * **Payload**: `{"api_key": "...", "amount": 1000}` (amount in cents, min $5.00) * **Response**: Client Secret & Payment Intent ID. #### D. Confirm Payment Refill * **Route**: `POST /api/portal/confirm-payment` * **Payload**: `{"api_key": "...", "payment_intent_id": "pi_..."}` * **Response**: Refilled balance profile details. --- ### User Authentication APIs * `POST /api/auth/signup` - Registers a new developer account (protected by CAPTCHA). * `POST /api/auth/login` - Authenticates credentials and starts session. * `POST /api/auth/logout` - Terminates current session. * `POST /api/auth/verify-email` - Verifies email with a verification code. * `POST /api/auth/verify-2fa` - Checks one-time 2FA codes. * `POST /api/auth/forgot-password` - Requests password reset code via email. * `POST /api/auth/reset-password` - Resets password using valid token. --- ### Administrative APIs (Role: admin) #### A. Admin Dashboard * **Route**: `GET /admin/dashboard` * **Access**: Requires Session Cookie with Role `"admin"` or Header `Authorization: <ADMIN_SECRET>`. #### B. API Key Management * **Route**: `GET/POST /api/admin/keys` * **GET**: Returns JSON array of all registered developers. * **POST**: Registers a new API key. ```json { "name": "Developer Name", "api_key": "optional-custom-key", "balance": 10.00 } ``` #### C. Refill Developer Credits * **Route**: `POST /api/admin/refill` * **Payload**: `{"api_key": "sk-...", "amount": 25.00}` --- ## 2. API Security Measures We enforce standard security controls across all network interfaces to mitigate exploitation, resource abuse, and data leakage: ### A. Transport Layer Security (TLS) * **Let's Encrypt Integration**: When `AUTOCERT_DOMAINS` is set, the gateway automatically provisions and renews TLS certificates via the ACME protocol on port 443. * **HTTPS Enforcement**: Directs all sensitive transmissions over TLS, avoiding plaintext eavesdropping. ### B. Device Signature Verification (HMAC-SHA256) * **Anti-Spoofing & Replay Protection**: For FindMe devices, request authentication uses a message authentication code computed via HMAC-SHA256: * Headers: `X-App-Signature` and `X-App-Timestamp`. * The signature is checked against `HMAC_SHA256(Timestamp + APIKey, Secret)`. * If the timestamp varies by more than **60 seconds** from the server's clock, the request is dropped. This blocks attackers from intercepting and replaying legitimate device requests. ### C. Advanced Timing Attack Defense * **Admin Tokens**: Checks admin authorization headers using Go's `subtle.ConstantTimeCompare`, neutralizing hackers from measuring response times to reconstruct secret keys byte-by-byte. ### D. Input / Output Guardrails (Safety Analysis) * **Jailbreak Mitigation**: Incoming prompts are evaluated to catch and block prompt injection or adversarial jailbreaking. * **PII Redaction**: Screens outgoing model completions to prevent accidentally leaking Personally Identifiable Information (emails, SSNs, credit card numbers, phone numbers). ### E. Rate Limiting (Token Bucket) * **DoS/Abuse Mitigation**: Prevents request floods using a thread-safe token bucket rate limiter: * Devices: Limited to `20 RPM` with a `5 burst` capacity. * Developers: Default `60 RPM` with a `10 burst` capacity. * Prevents brute-forcing login endpoints and downstream vector embedding API exhaustion. ### F. CAPTCHA Bot Blocking * **Automated Account Creation Blocking**: The signup page mandates a verified CAPTCHA (supporting both external reCAPTCHA and local image generation fallback) to block spam accounts. ### G. Payload Size Constraints * **Memory Protection**: Request bodies are parsed via `http.MaxBytesReader` to limit payload volumes (e.g. max 10MB for chat completion, 1MB for portal/authentication parameters), preventing memory exhaustion attacks (ZIP bombs/resource hogging). ### H. Cryptographic Storage * **Bcrypt Hash**: User credentials are stored as Bcrypt password hashes (never plaintext). * **Cryptographically Secure Entropy**: Employs `crypto/rand` (system-level entropy) for generating multi-factor tokens, password reset paths, and session keys.