Authentication

API Keys

All API requests require an API key passed in the X-API-Key header:

X-API-Key: tt_live_k1a2b3c4d5e6_s9x8y7z6w5v4u3t2r1q0p9o8n7m6l5k4

Key Format

Managing Keys

Get and manage your API keys in the API Dashboard:

• Generate: Click "Enable API Access" to generate your key
• Rotate: Click "Rotate Key" to invalidate the old key and generate a new one
• Disable: Click "Disable API Access" to revoke your key entirely

Idempotency

All POST requests require an Idempotency-Key header to prevent duplicate filings:

Idempotency-Key: your-unique-request-id

How It Works

1. Include a unique key (max 64 characters) with each POST request
2. If you retry with the same key and request body, you receive the original response
3. If you use the same key with a different body, you receive a 409 Conflict
4. Keys expire after 24 hours

Recommended Key Format

// Format: {type}-{company_number}-{period_end}
Idempotency-Key: ct600-12345678-2024-12-31

// Or use a UUID
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Rate Limits

API requests are rate limited to protect our infrastructure and HMRC/CH systems:

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 58
X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 847
X-RateLimit-Reset: 1705329600

When Exceeded

When you exceed the rate limit, you'll receive a 429 Too Many Requests response with a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 32

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please wait before retrying."
  }
}

Security Best Practices

• Store keys securely: Use environment variables or a secrets manager
• Never expose in client code: API calls should be server-side only
• Rotate regularly: Rotate keys periodically or after team changes
• Monitor usage: Check the API Dashboard for unexpected activity
• Use HTTPS: All API requests must use HTTPS (enforced)

Credentials

Government Gateway and Companies House credentials are passed per-request and never stored by TinyTax. They are:

• Transmitted over HTTPS only
• Never logged or persisted
• Cleared from memory after use

Authentication Errors