Guides

Authentication

Authenticate by giving an Aether SDK an API key. The SDK sends authenticated requests for you.

Get an API key

Create a key in the Aether Dashboard. API keys identify your organization and should only be used from server-side code, jobs, local development scripts, or trusted backend services.

Keep keys server-side

Never commit API keys, paste them into client-side code, ship them in mobile apps, or expose them in browser bundles. Store them in environment variables, deployment secrets, or a secrets manager.

Set the key

The SDKs look for AETHER_API_KEY when you construct a client without passing a key explicitly.

export AETHER_API_KEY="your-api-key"

If your app loads secrets under another name, pass that value into the client constructor instead.

Create a client

from aether import AetherClient

client = AetherClient()

An explicit key always wins over AETHER_API_KEY: use api_key in Python, apiKey in TypeScript, WithAPIKey in Go, or AetherClientOptions.ApiKey in .NET.

import os
from aether import AetherClient

client = AetherClient(api_key=os.environ["AETHER_API_KEY"])

How the SDK authenticates

The hosted API accepts bearer-token authentication. The SDKs derive that from your API key and attach the request header internally; your application code should normally work with SDK clients, not HTTP headers.

Use the raw header only when you are calling the REST API directly or debugging with an HTTP tool:

Bash
curl "https://api.aetherdb.ai/documents" \
  -H "Authorization: Bearer $AETHER_API_KEY"

Key roles

Most application code should use a regular key. Admin keys are for trusted control-plane operations, such as managing tenant keys or usage from an admin portal.

RoleUse forAvoid using for
RegularSDK-backed document insert, search, retrieval, and application workflowsTenant administration
AdminTrusted backend administration for your own tenantBrowser code, end-user apps, and routine document operations

If an endpoint requires an admin key and you use a regular key, the API returns 403 Forbidden.

Rotate a key

Rotate keys by running both keys during a short transition:

  1. Create a replacement key in the Dashboard.
  2. Add the replacement key to your secret store or deployment environment.
  3. Deploy or restart every service that uses Aether.
  4. Verify the new key works in production.
  5. Revoke the old key from the Dashboard.

Keep the overlap short, and rotate immediately if a key may have been logged, copied into source code, exposed in a browser bundle, or shared with someone who no longer needs access.

Storage best practices

  • Store production keys in your deployment platform's secrets manager or a dedicated secrets manager.
  • Use .env files only for local development, and keep them out of git.
  • Use different keys for local development, staging, and production.
  • Give each service its own key when you need independent revocation.
  • Do not print keys in logs, traces, analytics events, crash reports, or support screenshots.

Rate limits

Rate limits are enforced per organization. If you exceed your plan's rate limit, the API returns 429 Too Many Requests and includes a retry-after header with the minimum wait time in seconds.

The SDKs retry transient failures, including 429, with backoff and respect retry-after when the API sends it. For sustained traffic, still queue, throttle, or batch requests in your application. See Limits & quotas for account limits and Troubleshooting for backoff examples.