API Authentication

Authenticate with API keys or OAuth for secure access

AnomalyArmor supports two authentication methods:

Method	Use Case
API Keys	SDK, CLI, CI/CD pipelines, programmatic access
OAuth 2.1	MCP 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

Scope	Capabilities
read-only	GET endpoints only. Read assets, freshness, lineage, alerts.
read-write	GET + POST. Trigger freshness/schema refreshes.
admin	Full 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

read-only: Airflow pre-flight check

Check if data is fresh before running pipelines. No ability to modify anything.

# Just reads freshness status
client.freshness.require_fresh("warehouse.orders")

read-write: Trigger refresh after dbt run

Check freshness and trigger a refresh when needed.

# Can trigger refresh operations
client.freshness.refresh("warehouse.orders", wait=True)

admin: Key rotation automation

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

Environment Variable (Recommended)

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:

Tier	Max Keys	Rate Limit	Burst
Free Trial	1	20/min	2/sec
Starter	1	30/min	3/sec
Growth	10	500/min	25/sec
Professional	25	1,000/min	50/sec
Enterprise	Unlimited	5,000/min	100/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

401 Unauthorized

• Check the key is not revoked
• Verify the Authorization: Bearer header format
• Ensure no extra whitespace in the key

403 Forbidden

• The key is valid but lacks permission for this operation
• Check the scope - you may need read-write or admin

429 Rate Limited

• You’ve exceeded your rate limit
• Check Retry-After header for when to retry
• Consider upgrading your plan for higher limits