Minting a key
- Sign in at dashboard.segmentflow.ai.
- Open Settings → API Keys.
- Click Create API key, give it a label (e.g.
production-zapier), and pick the scopes it needs. - Copy the key — it’s shown once, never again. Store it in your secrets manager.
Using the key
Send the key on every request as thex-api-key header:
401 Unauthorized. A valid key without the required scope returns 403 Forbidden.
API Keys versus WriteKeys
API Keys authenticate the unified API and the server-side SDK. Use them from backend services, internal tools, and MCP hosts that call routes such as/api/v1/templates, /api/v1/emails, or /api/v1/events.
WriteKeys authenticate the Ingest API and browser/plugin event tracking. They are public, organization-level keys used by the browser SDK, Shopify, WooCommerce, and WordPress integrations. Do not use a WriteKey with the unified API, and do not put an API Key in browser code.
Members can read docs and delivery records in the dashboard. Organization owners and admins create or revoke API Keys and run dashboard test sends.
Scopes
Each key carries a fixed set of scopes. The v1 launch surface uses these scopes:| Scope | Resource | Grants |
|---|---|---|
profiles:read | Profiles | List Profiles, retrieve one Profile, and read a Profile’s subscription statuses. |
profiles:write | Profiles | Delete one Profile or perform bulk Profile deletion. |
templates:read | Templates | List and retrieve email Templates. |
templates:write | Templates | Create, update, delete, duplicate, archive, and unarchive Templates. |
assets:read | Assets | List Asset metadata. |
assets:write | Assets | Create Assets, request upload sessions, finalize uploads, update, and delete. |
brand-kit:read | Brand Kit | List Brand Kits, retrieve one Brand Kit, and read extraction progress. |
brand-kit:write | Brand Kit | Create, update, rename, delete, clear, set default, and extract Brand Kits. |
events:write | Events | Track server-side business events via events.track. |
emails:write | EmailSends | Create one EmailSend or batch create independent EmailSends. |
emails:read | EmailSends | Retrieve EmailSend status. |
Segments, direct Journey management, Broadcasts, anonymous web routes, and the
WriteKey Ingest API are outside the v1 SDK/MCP launch surface.
Rotating and revoking keys
Keys never expire automatically — rotate on a schedule that matches your security policy. Revoke a leaked key from Settings → API Keys → Revoke. Revocation takes effect within seconds; in-flight requests on a revoked key complete, but the next request returns401.
Idempotency
Some mutating endpoints accept anIdempotency-Key header. Send the same key with the same body to safely retry without acting twice.
Email idempotency keys are required and remain reserved for the lifetime of the EmailSend record. Reusing the same key with the same request returns the existing send with its current status. Reusing it with different request parameters returns 409 Conflict.
Event tracking idempotency keys are required. Reusing the same key with the same events.track request returns the original accepted event response. Reusing it with different request parameters returns 409 Conflict.
For other endpoints, follow the idempotency behavior documented on the endpoint’s API reference page.