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
- Open Settings → API Keys in the web console.
- Click + Create API Key.
- Name it ("Zapier production", "Internal ETL job"), pick permissions, click Create.
- 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 | campaign/create-and-schedule, flow/send-email-through-flow, nb-content/send-nb-email, contacts/refresh-segment, and the two lookup endpoints templates/get-email-templates and contacts/get-groups. |
contacts_access | contacts/add-group-members, contacts/profile/batch-update-custom-field, contacts/refresh-segment, contacts/get-groups, 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.
What sending_access covers
sending_access is the four endpoints that dispatch mail, plus the two read-only lookups you need to address a send:
| Endpoint | What it does |
|---|---|
POST campaign/create-and-schedule | Creates a one-time send from raw HTML or an existing template, and schedules it, in one request. See the cURL example. |
POST flow/send-email-through-flow | Enrols a contact into a flow and triggers its first email. |
POST nb-content/send-nb-email | Sends a direct transactional email. |
POST contacts/refresh-segment | Re-runs a segment's membership query. Also accepted with contacts_access. |
GET templates/get-email-templates | Lists your templates so you can pick a template_id. |
GET contacts/get-groups | Lists your lists and segments so you can pick a send_group_id. Also accepted with contacts_access. |
Two limits worth knowing before you design around this scope:
- There is no API equivalent of the console's Duplicate action. You can reuse a template by passing its
template_idtocampaign/create-and-schedule, but there is no "duplicate this send by id" call that copies an existing campaign's settings. If you need that, tell us — it doesn't exist yet. sending_accessalone can't build the audience. A one-time send needs an existingsend_group_id, and creating or populating lists needscontacts_access. Most automation ends up wanting both scopes on one key.
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_accesskey. 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.