Authentication

API key management, rate limits, and security practices for the Aether API.

API keys

All requests to the Aether API require an API key, passed in the Authorization header as a Bearer token:

Authorization: Bearer aeth_live_abc123def456

Key format

Aether API keys follow a consistent format:

aeth_{environment}_{random}

Test keys are useful for development and integration testing without triggering real affiliate tracking.

Obtaining a key

API access is currently available by request during the validation phase. To request a key, email hello@aethergraph.io with:

• Your name or company name
• A brief description of what you're building
• Whether you need a test key, a live key, or both

Keys are typically issued within 24 hours.

Key security

Your API key authenticates your requests and is tied to your rate limits and usage data. Keep it secure.

• Do not embed API keys in client-side code, public repositories, or browser-accessible JavaScript
• Store keys in environment variables or a secrets manager
• If you believe a key has been compromised, contact hello@aethergraph.io immediately — we will revoke and reissue it

Aether monitors API usage for anomalous patterns. If we detect unusual activity on a key (sudden volume spikes, requests from unexpected locations, or patterns consistent with scraping), we may contact you or temporarily suspend the key as a precaution.

Rate limits

Rate limits are applied per API key and vary by tier. Limits are communicated in the response headers of every request:

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

Tier limits

The price comparison endpoint (/v1/compare/{gtin}) has a separate, lower limit because it performs cross-merchant lookups and is more computationally expensive than a standard search.

What happens when you hit the limit

If you exceed your rate limit, the API responds with HTTP 403 and an error code of rate_limited:

{
  "status": "error",
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 2026-03-06T14:30:00Z"
  }
}

The response includes a Retry-After header indicating when you can resume requests. The best practice is to respect this header and implement exponential backoff in your integration.

Upgrading your tier

During the validation phase, all keys are issued at the Free tier. Pro and Enterprise tiers will be available once the API is in general availability. If your use case requires higher limits during validation, contact hello@aethergraph.io to discuss.

Authentication errors

If you receive a 401 error, check that:

1. The Authorization header is present in your request
2. The header value starts with Bearer (note the space)
3. The key is correctly copied with no trailing whitespace
4. The key has not been revoked

Best practices for agent integrations

If you're building an AI agent that calls the Aether API, these practices will help you stay within limits and get the best results.

Use the fields parameter. Default responses are already compact, but if you only need prices and merchant names, don't request description or images.additional. Smaller responses mean faster processing and lower token costs for your agent.

Cache category and merchant listings. The /v1/categories and /v1/merchants endpoints return data that changes infrequently. Cache these responses locally and refresh them at most once per day rather than calling them on every user query.

Let the API do the filtering. Use query parameters (min_price, max_price, brand, condition, in_stock) to narrow results server-side rather than fetching broad results and filtering in your agent. This is faster and uses fewer requests.

Use the compare endpoint for specific products. If your agent has identified a specific product (by GTIN), call /v1/compare/{gtin} directly rather than searching by name and hoping to match. The compare endpoint is purpose-built for this and returns cleaner results.

Respect Retry-After headers. If you hit a rate limit, wait for the specified time before retrying. Retrying immediately will not succeed and will slow down your recovery.