API Keys

API keys provide programmatic access to Aura's API. Use them to integrate with other systems, build custom workflows, or access data externally.

API Keys Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│ API KEYS                                                      [+ Create]    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │ NAME             CREATED        LAST USED       STATUS    ACTIONS       ││
│  ├─────────────────────────────────────────────────────────────────────────┤│
│  │ Production API   Jan 15, 2024   Today          Active      •••         ││
│  │ Staging Test     Dec 1, 2023    Jan 10         Active      •••         ││
│  │ Old Integration  Aug 5, 2023    Never          Revoked     •••         ││
│  └─────────────────────────────────────────────────────────────────────────┘│
│                                                                              │
│  ⚠️ API keys grant access to your organization's data. Keep them secure.   │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Creating an API Key

Step 1: Create Key

1. Go to Settings → API Keys
2. Click Create API Key

Step 2: Configure

Step 3: Copy Key

Your API Key:
aura_pk_live_aXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

⚠️ This will not be shown again. Store it securely.

[Copy to Clipboard]

Key Format

Production Keys

aura_pk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• Prefix: aura_pk_live_
• Access: Full production data
• Use: Production systems only

Test Keys

aura_pk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• Prefix: aura_pk_test_
• Access: Test environment
• Use: Development and testing

Using API Keys

Authentication

Include in request header:

curl -H "Authorization: Bearer aura_pk_live_XXXXX" \
     https://api.aura-app.ai/v1/leads

GraphQL

curl -X POST https://api.aura-app.ai/graphql \
  -H "Authorization: Bearer aura_pk_live_XXXXX" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ leads { edges { node { name email } } } }"}'

From any language

The API is plain HTTPS — any HTTP client works. For TypeScript projects, you can also generate a typed client from the public OpenAPI spec:

# Generate typed paths/responses from the live spec
npx openapi-typescript https://api.aura-app.ai/openapi.json -o aura-types.ts

For the canonical endpoint reference (every path, request body, response shape), see docs.api.aura-app.ai.

Managing Keys

View Key Details

Click on a key to see:

• Creation date
• Last used timestamp
• Request count
• Associated user

Rotate Key

To rotate (replace) a key:

1. Create new key
2. Update your systems
3. Verify new key works
4. Revoke old key

Revoke Key

To immediately disable a key:

1. Find the key
2. Click ••• → Revoke
3. Confirm revocation

Delete Key

To remove key completely:

1. Key must be revoked first
2. Click ••• → Delete
3. Confirm deletion

Security Best Practices

Key Storage

Do:

• Store in environment variables
• Use secrets management (Vault, AWS Secrets)
• Encrypt at rest

Don't:

• Commit to source control
• Share in Slack/email
• Log in application logs
• Embed in client-side code

Key Hygiene

• Rotate regularly: Every 90 days recommended
• Use separate keys: Production vs. staging
• Name descriptively: Know what each key does
• Review usage: Check for unexpected patterns

Environment Variables

# .env (never commit!)
AURA_API_KEY=aura_pk_live_XXXXX

// In code
const apiKey = process.env.AURA_API_KEY;

Rate Limits

Default Limits

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642234567

Handling Limits

When rate limited (429 response):

1. Check Retry-After header
2. Implement exponential backoff
3. Consider request optimization

Scopes & Permissions

API keys are issued with explicit scopes that gate which endpoints the key can call. A key carries one or more of: read, write, admin. Scopes are selected at key-creation time and cannot be changed afterward — to widen or narrow access, create a new key and revoke the old one.

For the authoritative list of scopes and what each one grants, see Reference → API Key Scopes.

Common patterns:

• Read-only integration: select read only — the key can list and fetch but never mutate.
• Standard partner integration: select read + write — can create/update leads, calls, payments.
• Webhook management: select admin — required to subscribe to webhooks or rotate webhook secrets via the API.

Keys are also tagged with an environment (live or test) — see the Key Format section above.

Audit Trail

All API key usage is logged:

• Request timestamp
• Endpoint called
• Response status
• IP address

View in Audit Trail section.

Key Lifecycle

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   ACTIVE    │────▶│   EXPIRED   │     │   DELETED   │
│             │     │  (if set)   │     │             │
└─────────────┘     └─────────────┘     └─────────────┘
       │                   │                   ▲
       │                   │                   │
       └───────────────────┼───────────────────┘
                           │
                    ┌─────────────┐
                    │   REVOKED   │
                    │             │
                    └─────────────┘

Troubleshooting

401 Unauthorized

1. Check key is copied correctly
2. Verify key is not revoked
3. Confirm Authorization header format
4. Check for extra whitespace

403 Forbidden

1. Key doesn't have access to resource
2. Organization plan limits
3. Resource belongs to different org

429 Rate Limited

1. Reduce request frequency
2. Implement caching
3. Use bulk endpoints
4. Contact support for limit increase

Next Steps

• API Overview - Full API documentation
• Endpoint reference - Full REST + GraphQL schema