Authentication

How AIsa authenticates requests: API keys as Bearer tokens for HTTP and SDKs, and OAuth sign-in for MCP and the CLI. Key limits, storage, rotation, and revocation.

AIsa accepts two kinds of credentials. Both draw on the same account balance.

Credential	Used by	How you get it
OAuth sign-in	MCP clients (https://mcp.aisa.one/mcp), the AIsa CLI	Approve once in the browser; the client stores and refreshes the token
API key	HTTP requests, SDKs, CI, servers	Create it in Console → API Keys

Agents should prefer OAuth: nobody copies a secret, and the user can sign out without rotating keys. Use an API key when code runs without a person present.

OAuth for MCP and the CLI

You do not create anything in advance.

• MCP. Add https://mcp.aisa.one/mcp to your client. On first use the server answers 401 with OAuth metadata (RFC 9728), the client opens a browser, and you click Allow. The client keeps the token; agents must not read or reuse it. Steps per client: Connect via MCP.
• CLI. aisa login runs the same browser flow and stores an auto-refreshing session in ~/.aisa/tokens.json. Check it with aisa balance. See Use the CLI.

An MCP client can also send an API key instead (Authorization: Bearer $AISA_API_KEY) when OAuth is not possible, for example in CI. For the CLI, setting AISA_API_KEY overrides the stored session.

Some account-wide views need OAuth. For example, GET /v1/usage with scope=account requires an OAuth session; an API key can only read its own usage.

API keys

Send the key as a Bearer token on every request:

curl https://api.aisa.one/v1/chat/completions \
  -H "Authorization: Bearer $AISA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4-mini","messages":[{"role":"user","content":"Hello"}]}'

The same key works for models (https://api.aisa.one/v1), data APIs (https://api.aisa.one/apis/v1), and MCP. The Anthropic-compatible /v1/messages route also accepts it as x-api-key, which is what the Anthropic SDK sends. See OpenAI / Anthropic SDK.

Key settings

When you create or edit a key in API Keys you can set:

• Name - label the key by app or environment, such as prod-web or ci.
• Spending limit - the most this key may spend, in USD, or Unlimited. The key can spend up to the lower of its remaining limit and your account balance. When the limit runs out the key’s status becomes exhausted and requests return 402 insufficient_api_key_balance.
• Allowed IPs - restrict the key to specific IP addresses or CIDR ranges.
• Status - disable a key temporarily without deleting it.

A practical pattern is one key per service or environment - a development key with a small limit, a production key with a larger one - so revoking one never interrupts the others.

Rotate and revoke

To rotate: create a new key, deploy it everywhere, confirm in Usage & Logs that the old key has stopped receiving traffic, then revoke the old key. Rotate on a schedule and immediately after anyone with access leaves.

If a key leaks, revoke it first and investigate afterwards. Requests with a disabled, expired, or invalid key return 401 (api_key_disabled, expired_api_key, invalid_api_key). See Errors.

Storing keys

Your API key has direct access to spend your account balance. Never commit it to git repositories, share it in chat, or include it in client-side code.

Local development

Keep the key in a .env file loaded by python-dotenv or dotenv, and add .env to .gitignore.

# .env
AISA_API_KEY=sk-...

CI/CD

Store the key as a CI secret and expose it as an environment variable. Give CI its own key with a low spending limit.

# GitHub Actions
env:
  AISA_API_KEY: ${{ secrets.AISA_API_KEY }}

Servers and cloud

Use your platform’s secret manager (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, or the encrypted environment variables of Fly, Render, or Railway). Rotating the secret and restarting picks up the new key.

Client-side apps

Never put a key in code a user can inspect. Call AIsa from a backend you control that authenticates your users, applies per-user limits, and forwards requests with the server-held key.

Related

Billing & Credits

How spend is metered, quoted, and capped.

Security & Privacy

Data handling, retention, and transport security.