API Authentication¶

Learn how to authenticate with the Aegis REST API.

Overview¶

The Aegis API uses two types of authentication:

Type	Header	Format	Use Case
Policy API Key	`X-Aegis-API-Key`	`aegis_sk_xxx`	Preflight checks
SDK License Key	`Authorization: Bearer`	`aegis_lic_xxx`	SDK operations

Policy API Key¶

Used for direct API access to preflight endpoints.

Getting Your API Key¶

Log in to the Aegis Dashboard
Navigate to your organization
Go to Policies and select a policy
Copy the API Key from the policy details

Using the API Key¶

Include the key in the X-Aegis-API-Key header:

curl -X POST https://api.aegispreflight.com/api/preflight/text \
  -H "X-Aegis-API-Key: aegis_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"text": "Check this content", "destination": "AI_TOOL"}'

Multiple API Keys¶

Each policy has its own API key. Use different keys for:

Different applications
Different environments (dev, staging, prod)
Different departments

SDK License Key¶

Used for SDK initialization and license validation.

Getting Your License Key¶

Log in to the Aegis Dashboard
Navigate to Organization Settings
Find the SDK License section
Copy the license key

Using the License Key¶

For SDK validation endpoint:

curl https://api.aegispreflight.com/v1/license/validate \
  -H "Authorization: Bearer aegis_lic_your_key_here"

Response:

{
  "valid": true,
  "expires": "2025-12-31T00:00:00Z",
  "org_id": "acme",
  "policy_groups": ["default", "engineering", "marketing"],
  "default_policy_group": "default"
}

Key Management¶

Key Rotation¶

Regenerate Policy API Key:

Go to the policy in the dashboard
Click Regenerate API Key
Update your applications with the new key

Key Rotation

Old keys are immediately invalidated when regenerated.

Key Security¶

Best Practices:

Never commit keys to source control
```
# Add to .gitignore
.env
.env.local
```

Use environment variables

export AEGIS_API_KEY="aegis_sk_xxx"
export AEGIS_LICENSE_KEY="aegis_lic_xxx"

Use secrets management in production
AWS Secrets Manager
HashiCorp Vault
Kubernetes Secrets
Restrict key permissions
Use read-only keys where possible
Scope keys to specific policies

Error Responses¶

401 Unauthorized¶

{
  "detail": "Invalid or missing API key"
}

Causes: - Missing X-Aegis-API-Key header - Invalid key format - Key doesn't exist

403 Forbidden¶

{
  "detail": "API key does not have permission for this operation"
}

Causes: - Key is valid but lacks permissions - Key is for a different organization - Policy is inactive

429 Too Many Requests¶

{
  "detail": "Rate limit exceeded",
  "retry_after": 60
}

Causes: - Exceeded rate limits - Wait and retry with exponential backoff

Rate Limits¶

Plan	Requests/Minute	Requests/Day
Trial	60	1,000
Standard	300	50,000
Enterprise	Custom	Custom

Rate limit headers are included in responses:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1704067200

Examples¶

Python¶

import requests

headers = {
    "X-Aegis-API-Key": "aegis_sk_xxx",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.aegispreflight.com/api/preflight/text",
    headers=headers,
    json={
        "text": "Check this content",
        "destination": "AI_TOOL"
    }
)

result = response.json()
print(result["decision"])

JavaScript¶

const response = await fetch(
  "https://api.aegispreflight.com/api/preflight/text",
  {
    method: "POST",
    headers: {
      "X-Aegis-API-Key": "aegis_sk_xxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Check this content",
      destination: "AI_TOOL",
    }),
  }
);

const result = await response.json();
console.log(result.decision);

cURL¶

curl -X POST https://api.aegispreflight.com/api/preflight/text \
  -H "X-Aegis-API-Key: aegis_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"text": "Check this content", "destination": "AI_TOOL"}'