Authentication

The Inception Agents API supports two authentication methods: API keys for external integrations and edge workers, and Supabase JWTs for dashboard users.

API Keys

API keys use the iak_ prefix followed by 32 alphanumeric characters:

iak_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Create and manage keys in Dashboard > Settings > API Keys.

Key Scopes

Keys can be scoped to limit access to specific operations:

Always assign the minimum scope required for your integration.

Bearer Token Authentication

All /api/v1/* endpoints require a Bearer token in the Authorization header:

Authorization: Bearer iak_your_api_key

curl

curl "https://inception-agents-api.inception-agents.workers.dev/api/v1/tenants/me" \
  -H "Authorization: Bearer iak_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Node.js (fetch)

const response = await fetch(
  "https://inception-agents-api.inception-agents.workers.dev/api/v1/tenants/me",
  {
    headers: {
      Authorization: "Bearer iak_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    },
  }
);

const data = await response.json();
console.log(data);

Python (requests)

import requests

response = requests.get(
    "https://inception-agents-api.inception-agents.workers.dev/api/v1/tenants/me",
    headers={
        "Authorization": "Bearer iak_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
    },
)

data = response.json()
print(data)

Supabase JWT Authentication

Dashboard users authenticate via Supabase Auth. The JWT is passed automatically by the dashboard client in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Supabase JWTs are short-lived and refreshed automatically by the Supabase client library. You do not need to manage these tokens manually when using the dashboard.

If you are building a custom frontend that authenticates against the same Supabase project, use the supabase-js client to obtain and refresh tokens:

import { createClient } from "@supabase/supabase-js";

const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);

const {
  data: { session },
} = await supabase.auth.getSession();

const response = await fetch(
  "https://inception-agents-api.inception-agents.workers.dev/api/v1/tenants/me",
  {
    headers: {
      Authorization: `Bearer ${session.access_token}`,
    },
  }
);

Key Rotation

Rotate API keys without downtime using the following procedure:

1. Create a new key in Dashboard > Settings > API Keys. Assign the same scope as the key being replaced.
2. Update all integrations to use the new key. Deploy edge workers, update environment variables, and reconfigure any third-party services.
3. Verify that all traffic is using the new key. Check Dashboard > Settings > API Keys for last-used timestamps.
4. Delete the old key once no traffic is using it.

Both keys remain active simultaneously during the transition period, so there is no downtime.

# Step 1: Create new key via API (requires admin scope)
curl -X POST "https://inception-agents-api.inception-agents.workers.dev/api/v1/tenants/me/keys" \
  -H "Authorization: Bearer iak_old_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-v2",
    "scope": "write"
  }'

# Step 4: Delete old key after migration
curl -X DELETE "https://inception-agents-api.inception-agents.workers.dev/api/v1/tenants/me/keys/key_id_here" \
  -H "Authorization: Bearer iak_new_key_here"

Error Responses

401 Unauthorized

Returned when the Authorization header is missing, malformed, or contains an invalid token.

{
  "error": "unauthorized",
  "message": "Missing or invalid authentication token.",
  "statusCode": 401
}

Common causes:

• No Authorization header present
• Header value does not start with Bearer
• API key has been deleted or does not exist
• Supabase JWT has expired and was not refreshed

403 Forbidden

Returned when the token is valid but the key lacks the required scope for the requested operation.

{
  "error": "forbidden",
  "message": "API key does not have the required scope for this operation.",
  "statusCode": 403,
  "requiredScope": "write"
}

Common causes:

• A read-scoped key was used for a POST/PUT/DELETE request
• A write-scoped key was used for an admin-only endpoint (e.g., tenant settings)

Security Best Practices

Never commit keys to version control. Add API keys to .gitignore and use environment variables instead.

# .env (do NOT commit this file)
INCEPTION_API_KEY=iak_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

# .gitignore
.env
.env.*

Use environment variables in all deployment environments:

// Cloudflare Workers
const apiKey = env.INCEPTION_API_KEY;

// Node.js
const apiKey = process.env.INCEPTION_API_KEY;

// Python
import os
api_key = os.environ["INCEPTION_API_KEY"]

Use least-privilege scopes. Assign read scope to analytics dashboards, write scope to edge workers that record events, and admin scope only to administrative tooling.

Rotate keys regularly. Rotate production keys at least every 90 days. Rotate immediately if a key may have been exposed.

Monitor key usage. Check last-used timestamps and request counts in Dashboard > Settings > API Keys. Investigate unexpected usage spikes.

Use separate keys per environment. Maintain distinct keys for development, staging, and production. Never reuse a production key in non-production environments.