Authentication — AAMOS API Docs

Getting an API Key

To access the AAMOS API, you need an API key. Sign up for a free account at aamos.ai/signup and generate a key from your dashboard under Settings → API Keys.

🔑

Keep your key secret. Your API key grants full access to your account. Never include it in client-side JavaScript, public repositories, or log files.

Request Format

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

http

Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxx

Here's a complete example with curl:

bash

curl https://api.aamos.ai/v1/vims/objects \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -H "Content-Type: application/json"

API Key format

Live keys follow the format:

ak_live_[32-character alphanumeric string]

Test keys (for sandbox) use:

ak_test_[32-character alphanumeric string]

Rate Limits

Rate limits are enforced per API key, per minute. Limits vary by plan:

Plan	Requests / minute	Requests / day	File uploads / day
Free	20	1,000	100
Starter	100	10,000	1,000
Pro	500	100,000	Unlimited

Rate limit headers are included in every response:

http

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1705312800

Error Responses

Authentication and authorization errors return appropriate HTTP status codes with a JSON body:

Status	Code	Description
401	`unauthorized`	Missing or invalid API key. Check your Authorization header.
403	`forbidden`	Your key doesn't have permission for this resource or endpoint.
429	`rate_limit_exceeded`	You've exceeded your plan's rate limit. Wait and retry, or upgrade your plan.
500	`internal_error`	Something went wrong on our side. Retry with exponential backoff.

Error response body format:

json

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key provided",
    "request_id": "req_a1b2c3d4e5"
  }
}

⚠️

Rate limit 429 handling: When you receive a 429, check the Retry-After header for the number of seconds to wait before retrying.

Complete Example

A fully authenticated request to list VIMS objects:

bash

curl -s https://api.aamos.ai/v1/vims/objects \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -H "Accept: application/json" | jq .