Aura Partner Integrations API

Enterprise REST API for external partner integrations including commission platforms, external mobile apps, and client booking widgets.

Getting Started

1. Get Your API Key

Log in to your Aura dashboard
Navigate to Settings → API Keys
Click Create API Key, give it a descriptive name (e.g. "Postman Testing"), and choose a scope (read, write, or admin)
Copy the key immediately — it is only shown once

Your key will look like: aura_pk_live_xxxxxxxxxxxxxxxxxxxxxxxx

2. Make Your First Request

Test your API key with a simple health check and then an authenticated request:

# No auth required
curl https://api.aura-app.ai/health

# Authenticated request — replace with your key
curl -H "Authorization: Bearer aura_pk_live_xxxxx" \
  https://api.aura-app.ai/v1/leads

Environments

Environment	Base URL	Use
Production	`https://api.aura-app.ai`	Live data
Staging	`https://staging-api.aura-app.ai`	Pre-production testing
Local	`http://localhost:3001`	Local development

Test keys are read-only. Keys are prefixed aura_pk_live_… or aura_pk_test_…. A test-prefixed key can read your production data but cannot create, update, or delete — write/admin calls return 403. A fully isolated sandbox dataset is planned; until then, use a test key to safely explore the read endpoints.

3. Explore the API

Browse the endpoint reference in the sidebar
Download the OpenAPI spec for Postman or other tools
Read the GraphQL guide and download the GraphQL schema
Use the TypeScript client guide for the generated REST client

Authentication

REST partner endpoints under /v1 require a partner API key. The GraphQL endpoint accepts partner API keys and Clerk organization JWTs:

1. API Key (for partners and integrations):

Authorization: Bearer aura_pk_live_xxxxxxxxxxxxxxxx

Get your API key from the Aura dashboard at Settings → API Keys.

2. Clerk organization JWT (GraphQL, for mobile and web apps):

Authorization: Bearer <clerk_jwt_token>

Use Clerk's authentication SDK to obtain a JWT token with user and organization claims. Permissions follow the organization role. See Making requests for scopes, pagination and error handling.

Rate Limiting

Per source IP: 200 requests/minute
Per API Key: 100 requests/minute
Per Organization: 1000 requests/minute

Rate limit headers are included on responses:

X-RateLimit-Limit: Maximum requests allowed
X-RateLimit-Remaining: Remaining requests in current window
X-RateLimit-Reset: Unix timestamp when limit resets
Retry-After: Seconds to wait before retrying (sent on 429 responses)

On a 429, back off using Retry-After rather than retrying immediately. Limits are enforced per region and are approximate under high concurrency.

Idempotency

Safely retry unsafe writes by sending an Idempotency-Key header (any unique string, e.g. a UUID) on POST /v1/payments:

curl -X POST https://api.aura-app.ai/v1/payments \
  -H "Authorization: Bearer aura_pk_live_xxxxx" \
  -H "Idempotency-Key: 8f3a1c2e-3b9d-4f5a-9c7e-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{ "lead_id": "...", "amount": 5000.00, "currency": "USD", "payment_date": "2026-06-12", "status": "succeeded", "source": "stripe" }'

If a request with the same key has already succeeded, the original response is replayed and no duplicate payment is created. A request still being processed returns 409 — retry shortly. Keys are scoped to your organization.

API Endpoints

Leads

List leads - Retrieve paginated list of leads
Get lead - Get a specific lead by ID

Calls

List calls - Retrieve paginated list of calls
Get call - Get a specific call by ID

Team

List team members - Retrieve team members with roles and commission rates
Get team member - Get a specific team member by ID

Booking Links

List booking links - Retrieve booking links
Get booking link - Get a specific booking link

Products

List products - Retrieve product catalog
Get product - Get a specific product

Payments

List payments - Retrieve payment records
Get payment - Get a specific payment

Webhooks

New to webhooks? Start with the Webhooks guide — it covers the full flow end-to-end including HMAC signature verification, the retry policy, the event catalog, and drop-in Node/Python verification code.

REST endpoints for managing subscriptions:

List webhooks - List webhook subscriptions
Create webhook - Subscribe to events
Get webhook - Get a specific webhook subscription
Update webhook - Update a webhook subscription
Delete webhook - Remove a webhook subscription
Test webhook - Send a test event to a webhook

Error Handling

All errors follow a standard format:

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE",
  "requestId": "req_abc123"
}

Common HTTP status codes:

400 Bad Request - Invalid input
401 Unauthorized - Missing or invalid API key
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

Leads without a booked meeting

Use Calls: intent calls and form answers to find a lead's booking intent and retrieve submitted answers. A lead ID identifies the person; an intent call ID identifies their booking attempt. See the Webhooks guide for the lifecycle events available in Settings and Zapier.

Overview