keys-for-all/docs/API_SPECIFICATION.md

Keys for All - API Specification

Base URL

Production: https://api.keysforall.com/v1
Development: http://localhost:3000/v1

Authentication

All API requests require authentication using an API key in the header:

X-API-Key: your-api-key-here

Endpoints

Key Management

Generate Keys

POST /keys/generate

Request Body:

{
  "count": 5,
  "type": "purchase",
  "metadata": {
    "app_id": "com.voiceuwu.app",
    "purchase_id": "SK123456789",
    "price": 19.99
  }
}

Response:

{
  "success": true,
  "keys": [
    {
      "key": "ABCD-EFGH-IJKL-MNOP",
      "created_at": "2024-01-20T10:00:00Z",
      "expires_at": null,
      "type": "purchase"
    }
  ],
  "transaction_id": "txn_123456"
}

Validate Key

POST /keys/validate

Request Body:

{
  "key": "ABCD-EFGH-IJKL-MNOP",
  "app_id": "com.voiceuwu.app"
}

Response:

{
  "valid": true,
  "key_info": {
    "created_at": "2024-01-20T10:00:00Z",
    "first_used_at": "2024-01-20T10:05:00Z",
    "uses_remaining": null,
    "level": 1
  }
}

Activate Key

POST /keys/activate

Request Body:

{
  "key": "ABCD-EFGH-IJKL-MNOP",
  "app_id": "com.voiceuwu.app",
  "device_id": "iPhone14,2",
  "metadata": {
    "app_version": "1.2.0",
    "os_version": "17.2"
  }
}

Response:

{
  "success": true,
  "activation": {
    "id": "act_123456",
    "activated_at": "2024-01-20T10:05:00Z",
    "level": 1
  }
}

Get Key Status

GET /keys/{key}/status

Response:

{
  "key": "ABCD-EFGH-IJKL-MNOP",
  "status": "active",
  "created_at": "2024-01-20T10:00:00Z",
  "activations": 1,
  "shares": 0,
  "level": 1
}

Key Sharing

Create Share Link

POST /keys/share

Request Body:

{
  "key": "ABCD-EFGH-IJKL-MNOP",
  "count": 1,
  "expires_in": 86400,
  "message": "Enjoy this key!"
}

Response:

{
  "success": true,
  "share": {
    "id": "shr_123456",
    "code": "SHARE-CODE-123",
    "url": "https://keysforall.com/claim/SHARE-CODE-123",
    "expires_at": "2024-01-21T10:00:00Z"
  }
}

Claim Shared Key

POST /keys/claim

Request Body:

{
  "share_code": "SHARE-CODE-123",
  "app_id": "com.voiceuwu.app"
}

Response:

{
  "success": true,
  "key": {
    "key": "WXYZ-1234-5678-9ABC",
    "level": 1,
    "from": "anonymous"
  }
}

Community Pool

Donate to Pool

POST /community/donate

Request Body:

{
  "keys": ["ABCD-EFGH-IJKL-MNOP"],
  "message": "Happy to help the community!",
  "anonymous": true
}

Response:

{
  "success": true,
  "donation": {
    "id": "don_123456",
    "keys_donated": 1,
    "pool_size": 42
  }
}

Request from Pool

POST /community/request

Request Body:

{
  "app_id": "com.voiceuwu.app",
  "reason": "Student learning voice training",
  "email": "user@example.com"
}

Response:

{
  "success": true,
  "request": {
    "id": "req_123456",
    "status": "pending",
    "queue_position": 5
  }
}

Get Pool Status

GET /community/status

Response:

{
  "pool": {
    "available_keys": 42,
    "pending_requests": 15,
    "total_donated": 1337,
    "total_distributed": 1295
  },
  "stats": {
    "donations_today": 5,
    "requests_today": 8,
    "average_wait_time": 3600
  }
}

Purchase Verification

Verify StoreKit Purchase

POST /purchase/verify

Request Body:

{
  "receipt_data": "base64-encoded-receipt",
  "product_id": "com.voiceuwu.keys.pack5",
  "transaction_id": "1000000123456789"
}

Response:

{
  "success": true,
  "verification": {
    "valid": true,
    "product_id": "com.voiceuwu.keys.pack5",
    "keys_granted": 5,
    "keys": ["ABCD-EFGH-IJKL-MNOP", "..."]
  }
}

Analytics

Get App Statistics

GET /analytics/app/{app_id}

Response:

{
  "app_id": "com.voiceuwu.app",
  "period": "30d",
  "stats": {
    "keys_activated": 150,
    "keys_shared": 45,
    "active_users": 120,
    "conversion_rate": 0.15
  }
}

Error Responses

All errors follow this format:

{
  "error": {
    "code": "INVALID_KEY",
    "message": "The provided key is not valid",
    "details": {
      "key": "XXXX-XXXX-XXXX-XXXX"
    }
  }
}

Error Codes

• INVALID_KEY - Key format or validation failed
• KEY_ALREADY_USED - Key has been activated elsewhere
• KEY_EXPIRED - Key has passed expiration date
• RATE_LIMITED - Too many requests
• INVALID_API_KEY - Authentication failed
• INSUFFICIENT_KEYS - Not enough keys to share
• POOL_EMPTY - Community pool has no keys

Rate Limits

• Key validation: 100 requests per minute
• Key generation: 10 requests per minute
• Community requests: 1 per hour per IP
• General API: 1000 requests per hour

Webhooks

Apps can register webhooks for events:

Webhook Events

• key.activated - When a key is activated
• key.shared - When a key is shared
• pool.donation - When keys are donated
• purchase.verified - When a purchase is verified

Webhook Payload

{
  "event": "key.activated",
  "timestamp": "2024-01-20T10:05:00Z",
  "data": {
    "key": "ABCD-EFGH-IJKL-MNOP",
    "app_id": "com.voiceuwu.app",
    "level": 1
  }
}