Authentication

Overview

TOWN uses API keys to authenticate every request to the platform. Each request must include a valid secret key in the Authorization header. Keys are environment-specific and should never be shared publicly.

• • Use sandbox keys for development and testing.
• • Use production keys only in live environments.
• • Always send requests over HTTPS.

API Key Types

sk_sandbox_1234567890abcdefghijklmnopqrstuvwxyz

Making Requests

Authenticate requests by sending your secret key in the Authorization header using the Bearer scheme.

curl https://api.town.dev/v1/transactions \
  -H "Authorization: Bearer sk_sandbox_1234567890abcdefghijklmnopqrstuvwxyz" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "USD",
    "userId": "user_123",
    "type": "deposit"
  }'

Always use your secret key on the server side. Never embed secret keys in client-side code or mobile apps.

Error Handling

Authentication errors are returned with standard HTTP status codes and a JSON body describing the issue.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or expired."
  }
}

• 401 Unauthorized – Missing or invalid API key.
• 403 Forbidden – Key exists but doesn't have permissions for this resource.
• 429 Too Many Requests – Rate limit exceeded.