Authentication

All Afternoon API endpoints (except the health check) require authentication via an API key sent as a Bearer token in the Authorization header.

Obtaining an API key

API keys are created from the Afternoon dashboard. Each key is scoped to a single company and has one of two modes:

Making authenticated requests

Include your API key in the Authorization header of every request:

$
curl https://api.afternoon.co/v1/customers \
>
  -H "Authorization: Bearer ak_live_YOUR_API_KEY"

Error responses

The API returns specific error codes for authentication failures:

Missing or malformed header

Returned when the Authorization header is absent or does not follow the Bearer <token> format.

1
{
2
  "success": false,
3
  "error": {
4
    "code": "UNAUTHORIZED",
5
    "message": "Missing or invalid Authorization header"
6
  },
7
  "request_id": "req_abc123"
8
}

Status: 401 Unauthorized

Invalid API key format

Returned when the token is present but does not match the expected ak_live_* or ak_test_* pattern.

1
{
2
  "success": false,
3
  "error": {
4
    "code": "INVALID_API_KEY",
5
    "message": "Invalid API key format"
6
  },
7
  "request_id": "req_abc123"
8
}

Status: 401 Unauthorized

Invalid API key

Returned when the token format is valid but the key does not exist.

1
{
2
  "success": false,
3
  "error": {
4
    "code": "INVALID_API_KEY",
5
    "message": "Invalid API key"
6
  },
7
  "request_id": "req_abc123"
8
}

Status: 401 Unauthorized

Revoked API key

Returned when the API key has been revoked from the dashboard.

1
{
2
  "success": false,
3
  "error": {
4
    "code": "API_KEY_REVOKED",
5
    "message": "API key has been revoked"
6
  },
7
  "request_id": "req_abc123"
8
}

Status: 401 Unauthorized

Service unavailable

Returned when the authentication service cannot reach the database. Retry with exponential backoff.

1
{
2
  "success": false,
3
  "error": {
4
    "code": "SERVICE_UNAVAILABLE",
5
    "message": "Authentication service unavailable"
6
  },
7
  "request_id": "req_abc123"
8
}

Status: 503 Service Unavailable

Rate limiting

Authenticated requests are subject to rate limits of 1,000 requests per 60-second window per company. Rate limit status is communicated via response headers:

When the limit is exceeded, the API returns a 429 Too Many Requests response.

Security best practices

• Rotate keys regularly — Generate new keys and revoke old ones from the dashboard.
• Use test keys for development — Keep ak_test_ keys for staging and local development. Use ak_live_ keys only in production.
• Store keys securely — Use environment variables or a secrets manager. Never commit keys to source control.
• Monitor usage — Check the dashboard for unexpected spikes in API usage that may indicate a compromised key.