API Authentication

API Key Format

ASTRA OS API keys use a structured format that encodes the key type and environment:

astra_sk_live_abc123def456ghi789jkl012mno345pqr678

Passing the Key

Include your API key in the Authorization header as a Bearer token on every request:

curl https:"color: #6b7280">//astraos.cloud/api/v1/search \
  -H "Authorization: Bearer astra_sk_live_your_key_here"

import requests
headers = {
    "Authorization": "Bearer astra_sk_live_your_key_here"
}
response = requests.get(
    "https://astraos.cloud/api/v1/search",
    headers=headers,
    params={"bbox": "-122.5,37.5,-122.0,38.0"}
)

const response = await fetch(
  "https://astraos.cloud/api/v1/search?bbox=-122.5,37.5,-122.0,38.0",
  {
    headers: {
      Authorization: "Bearer astra_sk_live_your_key_here",
    },
  }
);

Key Management

Manage your API keys from the Dashboard → API Keys page. You can:

• ●Create keys with optional labels to identify each integration
• ●Revoke keys instantly to cut off access if a key is compromised
• ●Roll keys to generate a replacement key while the old key remains active for a grace period (24 hours)
• ●View usage per key including request count, last used timestamp, and error rate

Authentication Errors

When authentication fails, the API returns a JSON error with a descriptive message:

"color: #6b7280">// 401 Unauthorized — missing or invalid key
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key. Check that your key is correct and has not been revoked."
  }
}
"color: #6b7280">// 403 Forbidden — key does not have access to this resource
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Your current plan does not include access to processing endpoints. Upgrade at astraos.cloud/dashboard/billing."
  }
}

Rate Limits

Rate limits vary by plan tier and are enforced per API key. Exceeding your limit returns a 429 Too Many Requests response with a Retry-After header.

Rate limit headers are included on every response:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1706140800
Retry-After: 12