API keys & permissions

Mint and manage API keys in Settings → API Keys. Each key is scoped to one or more permissions so you can give narrow, least-privilege access to any integration.

Creating a key

1. Open Settings → API Keys in the web console.
2. Click + Create API Key.
3. Name it ("Zapier production", "Internal ETL job"), pick permissions, click Create.
4. Copy the token shown in the reveal dialog. This is the only time the full token is displayed. Store it in your secret manager immediately.

Permission scopes

| Scope | What it grants | | --- | --- | | full_access | Every public API endpoint. Treat like a root password. | | sending_access | flow/send-email-through-flow, nb-content/send-nb-email, and related dispatch endpoints. | | contacts_access | contacts/add-group-members, profile/batch-update-custom-field, and related contact writes. | | analytics_access | Read-only analytics: stats/*, analytics/*. |

A key with full_access bypasses every scope check; otherwise the server verifies the requested endpoint against the key's scope list on every request and returns 403 Forbidden on mismatch.

Rotating keys

Generate the replacement first, roll it into your secret store, and only then delete the old key. Deletion is immediate and revokes all in-flight requests.

Using a key

Pass it in the X-Api-Token header on every request:

curl https://api.aigeon.ai/public/api/v1/stats/get-org-stats \
  -H "X-Api-Token: sk_..."

The Aigeon SDKs (Node, Python) pick the key up from the AIGEON_API_KEY environment variable automatically — see the Node.js and Python examples.

Best practices

• One key per integration. Never share a key between services; rotating becomes impossible when it breaks.
• Use the narrowest scope that works. If all you do is push contacts, mint a contacts_access key. Blast radius on key exposure shrinks dramatically.
• Don't ship keys in client-side bundles. Only call the Aigeon API from servers, never from browser JavaScript. For browser signups, use a signup widget instead.
• Audit regularly. The Last Used column on the API Keys page makes unused keys obvious — delete them.