Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.anomalyarmor.ai/llms.txt

Use this file to discover all available pages before exploring further.

AnomalyArmor supports two authentication methods:
MethodUse Case
API KeysSDK, CLI, CI/CD pipelines, programmatic access
OAuth 2.1MCP server connections from AI tools (Claude Code, Cursor)
For MCP integrations, see the MCP Server page. OAuth authentication is handled automatically when you connect via the remote MCP server. The rest of this page covers API key authentication for programmatic access.

​
API Key Format

API keys use the format aa_live_<random>: 
aa_live_k8jd92hf8j2hd98fh2d9h2f98h2d9fh2
API keys are shown only once at creation. Store them securely - we cannot retrieve them later.

​
Creating API Keys

​
Via Dashboard

  1. Go to Settings > API Keys
  2. Click Create API Key
  3. Enter a descriptive name (e.g., “Airflow Production”)
  4. Select scope based on needs: read-only for monitoring, read-write for triggering actions, admin for key management
  5. Click Create Key
  6. Copy the key immediately

​
Via CLI

# Create a read-only key
armor api-keys create --name "airflow-prod" --scope read-only

# Create a read-write key for triggering refreshes
armor api-keys create --name "ci-pipeline" --scope read-write

​
Via API

curl -X POST "https://api.anomalyarmor.ai/api/v1/api-keys" \
  -H "Authorization: Bearer aa_live_admin_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "automation-key", "scope": "read-only"}'

​
Scopes

ScopeCapabilities
read-onlyGET endpoints only. Read assets, freshness, lineage, alerts.
read-writeGET + POST. Trigger freshness/schema refreshes.
adminFull access including API key management.
Follow the principle of least privilege - use read-only for monitoring and read-write only when you need to trigger actions.

​
Scope Examples

Check if data is fresh before running pipelines. No ability to modify anything.
# Just reads freshness status
client.freshness.require_fresh("warehouse.orders")
Check freshness and trigger a refresh when needed.
# Can trigger refresh operations
client.freshness.refresh("warehouse.orders", wait=True)
Create and revoke keys programmatically for security compliance.
# Can manage API keys
new_key = client.api_keys.create(name="rotated-key", scope="read-only")
client.api_keys.revoke(old_key_id)

​
Using API Keys

export ARMOR_API_KEY="aa_live_your_key_here"
Then in your code: 
from anomalyarmor import Client

# Automatically uses ARMOR_API_KEY
client = Client()

​
Direct Parameter

from anomalyarmor import Client

client = Client(api_key="aa_live_your_key_here")

​
HTTP Header

For direct API calls: 
curl -H "Authorization: Bearer aa_live_your_key_here" \
  https://api.anomalyarmor.ai/api/v1/assets

​
Rate Limits by Tier

Rate limits are set when you create the API key based on your subscription:
TierMax KeysRate LimitBurst
Free Trial120/min2/sec
Starter130/min3/sec
Growth10500/min25/sec
Professional251,000/min50/sec
EnterpriseUnlimited5,000/min100/sec
When you upgrade your plan, existing API keys automatically get the new rate limits.

​
Revoking Keys

Revoke compromised or unused keys immediately:

​
Via Dashboard

  1. Go to Settings > API Keys
  2. Find the key and click the trash icon
  3. Confirm revocation

​
Via CLI

armor api-keys revoke <key-id>

​
Via API

curl -X DELETE "https://api.anomalyarmor.ai/api/v1/api-keys/<key-id>" \
  -H "Authorization: Bearer aa_live_admin_key"

​
Security Best Practices

Use Environment Variables

Never hardcode API keys in source code. Use environment variables or secrets managers.

Rotate Regularly

Rotate keys periodically, especially for production systems.

Least Privilege

Use the minimum scope required. Most integrations only need read-only.

Separate Keys

Use different keys for different environments (dev, staging, prod).

​
Troubleshooting

  • Check the key is not revoked
  • Verify the Authorization: Bearer header format
  • Ensure no extra whitespace in the key
  • The key is valid but lacks permission for this operation
  • Check the scope - you may need read-write or admin
  • You’ve exceeded your rate limit
  • Check Retry-After header for when to retry
  • Consider upgrading your plan for higher limits

​
Common Questions

​
How do I create an API key?

Generate keys under Settings > API Keys in the dashboard, via armor api-keys create --name ... --scope ..., or by POSTing to /api/v1/api-keys with an admin key. Name keys after the integration that uses them (“airflow-prod”, “ci-pipeline”) so rotation and revocation stay auditable. The plaintext key is shown only once at creation.

​
Which scope should my API key have?

Use read-only for monitoring, dashboards, and CI checks that only query state. Use read-write when you need to trigger freshness or schema refreshes. Reserve admin for key management automation itself. Follow least privilege: most integrations only need read-only.

​
What does the aa_live_ prefix on a key mean?

All AnomalyArmor API keys start with aa_live_ followed by a random secret, making them easy to detect with secret scanners and grep over source trees. Treat the full string as sensitive. If you see one committed to git or pasted in logs, revoke it immediately from Settings > API Keys.

​
How do I rotate or revoke an API key?

Create the replacement key first, roll it out to the consumer, then revoke the old key via the dashboard, armor api-keys revoke <key-id>, or DELETE /api/v1/api-keys/{key-id} with an admin token. Revocation takes effect immediately and cannot be undone, so keep the new key live before cutting the old one.

​
Where should I store API keys in code?

Read the key from the ARMOR_API_KEY environment variable (Python SDK / CLI) or ANOMALYARMOR_API_KEY (TypeScript SDK CLI shim), and inject it from a secrets manager in production. Never hardcode keys in source, Docker images, or Jupyter notebooks. Use separate keys per environment so a dev leak can’t touch prod.

​
Why am I getting 403 Forbidden when my key works elsewhere?

403 means the key is valid but doesn’t have the scope the endpoint requires. Write endpoints (freshness refresh, schema refresh, create-metric) need read-write; key management needs admin. The error body shows current_scope and required_scope so you can pick the right key.