Authentication

Sequenzy API Keys settings with callouts showing how to create an API key

The Sequenzy API uses API keys for authentication. Every request must include your API key in the Authorization header.

Choose the right API key

Sequenzy supports two key types:

Workspace API keys (seq_live_) belong to one company. Create them in Workspace Settings → API Keys for production services that should stay isolated to that workspace.
Account API keys (seq_user_) follow your user account and can access every workspace you own or have non-restricted access to. Create and revoke them in Account Settings → API Keys. They are useful for administration, CLI/MCP clients, and multi-workspace automation.

Account keys preserve workspace membership roles: owner and admin memberships can use granted write permissions, marketer memberships can use marketing permissions (campaigns, sequences, emails, forms, landing pages, subscribers, lists, tags, segments, analytics, inbox) but not transactional, settings, integration, webhook, team, or API-key permissions, and viewer memberships remain read-only even when the key has a broader preset. Marketer keys are also refused on workspace-management routes that happen to sit inside marketing scopes: sending domain creation and verification, landing page custom domains, sequence inbound webhook secrets, integration details and activity, sync rules, tracking settings, and transactional delivery data (emailType=transactional metrics and email sends). Subscriber activity, recipient metrics, and audience drilldowns include only campaign and sequence email data for marketers. Transactional email templates cannot be reused to create campaigns. These restrictions apply equally to the dashboard, REST API, CLI, and MCP. The same source restrictions apply when creating or restarting A/B tests from existing emails. Campaigns backed by transactional templates are also protected when reading their audience, changing labels, deleting them, or managing share links, metrics, recipient drilldowns, and revenue attribution. Existing A/B tests with transactional-backed variants are protected when reading, editing, copying, selecting a winner, or rendering previews. Sequences that reference a transactional template, including alternate email styles or A/B variants, are also hidden from marketers and cannot be edited, copied, activated, or test-sent by them. Protected campaign, sequence, and A/B sources remain hidden in sent-email history and event details. Sequence restrictions also cover analytics leaderboards, recipient drilldowns, revenue reports, and subscriber enrollment summaries. These rules also apply to incoming email links when editing a sequence. Marketers can still test marketing emails, unschedule campaigns, and read existing sending domains to choose a sender. Workspace API key creation requires an owner or admin; marketers can use an account key through their own account settings. Account keys use the same permission presets as workspace keys. Their selected permissions apply in every accessible workspace, so prefer the narrowest preset that fits the automation.

Getting Your API Key

Sequenzy API key dialog with callouts showing purpose, preset, and permissions

Log in to your Sequenzy dashboard
Open Workspace Settings → API Keys for a workspace key, or Account Settings → API Keys for an account key
Click Create API Key
Give your key a descriptive name (e.g., “Production Backend”, “AI Drafting Agent”)
Choose a permission preset or custom permissions
Copy and securely store your key—it won’t be shown again

Keep your API key secret. Never expose it in client-side code, public repositories, or logs. Treat it like a password.

Using Your API Key

Include your API key in the Authorization header with every request:

Authorization: Bearer YOUR_API_KEY

Example Request

curl "https://api.sequenzy.com/api/v1/subscribers" \
  -H "Authorization: Bearer seq_live_abc123..."

Select a workspace with an account key

Pass the target workspace in x-company-id whenever you use a seq_user_ account key:

curl "https://api.sequenzy.com/api/v1/subscribers" \
  -H "Authorization: Bearer seq_user_abc123..." \
  -H "x-company-id: company_abc123"

The same account key works for newly created workspaces as soon as your account can access them. If you omit x-company-id, Sequenzy selects the first accessible workspace; multi-workspace integrations should always send the header explicitly.

Example in Code

const response = await fetch("https://api.sequenzy.com/api/v1/subscribers", {
  headers: {
    Authorization: `Bearer ${process.env.SEQUENZY_API_KEY}`,
    "Content-Type": "application/json",
  },
});

API Key Best Practices

1. Use Environment Variables

Never hardcode API keys in your source code:

// Good
const apiKey = process.env.SEQUENZY_API_KEY;

// Bad
const apiKey = "seq_live_abc123..."; // Don't do this!

2. Create Separate Keys for Each Environment

Production key: Used only on production servers
Development key: Used for local development and testing
CI/CD key: Used for automated testing (if needed)

This way, if a development key is compromised, your production data stays safe.

3. Rotate Keys Periodically

If you suspect a key has been compromised:

Create a new API key
Update your application to use the new key
Delete the old key

Key validation results are cached briefly for performance, so a deleted key can keep working for up to five minutes before requests start failing. Rotation is for compromised keys. If a key simply has the wrong permissions, edit them in place instead - from Settings, the CLI (sequenzy api-keys update), the API, or MCP’s update_api_key. The key value stays the same, so nothing holding it needs to be re-wired, and widened permissions apply on the next retry. Removed permissions may remain usable for up to five minutes while API caches expire.

4. Use the Smallest Permission Set

When creating a key, choose the narrowest preset that fits the integration:

Read-only for reporting, dashboards, and audits
Safer agent access for AI agents that should inspect data, define lists and tags, tag existing contacts, set up the workspace, draft content, and edit sequence A/B variant copy without changing list membership, sending live emails, or deleting records
AI drafting for agents that can inspect data, set up the workspace, and draft content but must not send real emails
Data ingest, no automations for syncing contacts and events without starting automations
Transactional sender only for backend services that need to send transactional emails

Use custom permissions when a preset is close but too broad. Sending real emails requires explicit delivery permissions such as campaigns:send, sequences:activate, sequences:enroll, transactional:send, automations:trigger, or conversations:write. Destructive deletes require explicit *:delete permissions. Some permissions are deliberately narrow so a read-mostly key does not have to be widened to do one job. subscribers:tag adds and removes tags on contacts that already exist without granting the ability to create, update, or unsubscribe them; subscribers:write includes it. lists:write and tags:write define lists and tags but do not change who belongs to them - adding contacts to a list or removing them from it requires subscribers:write as well, and deleting the list or tag requires lists:delete or tags:delete.

5. Never Commit Keys to Git

Add your environment file to .gitignore:

# .gitignore
.env
.env.local
.env.production

6. Use Secrets Management in Production

For production deployments, use your platform’s secrets management:

Vercel: Environment Variables in dashboard
AWS: AWS Secrets Manager or Parameter Store
Heroku: Config Vars
Docker: Docker Secrets or environment variables

Authentication Errors

401 Unauthorized

{
  "success": false,
  "error": "Unauthorized"
}

This error occurs when:

The API key is missing from the request
The API key is invalid or has been deleted
The API key format is incorrect

Solution: Check that you’re including the Authorization: Bearer YOUR_KEY header with a valid key.

Common Mistakes

Mistake	Correct Format
Missing “Bearer” prefix	`Authorization: Bearer sk_live_...`
Using `X-API-Key` header	Use `Authorization` header instead
Exposing key in URL	Pass key in header, not query params
Using test key in production	Use `sk_live_` prefix for production

Managing API Keys

View Active Keys

In Workspace Settings → API Keys or Account Settings → API Keys, you can see:

Key name
Created date
Last used timestamp

Delete a Key

To revoke access:

Go to the API Keys page where the key was created
Find the key you want to delete
Click Delete
Confirm the deletion

Deleting a key immediately invalidates it. Any requests using that key will start failing.

Security Recommendations

Server-Side Only

Only use API keys in server-side code. Never expose them to browsers:

// Server-side (Node.js, Next.js API route) - Safe
export async function POST(request) {
  const response = await fetch("https://api.sequenzy.com/api/v1/...", {
    headers: { Authorization: `Bearer ${process.env.SEQUENZY_API_KEY}` },
  });
}

// Client-side (React component) - NEVER do this
function Component() {
  // This exposes your key to anyone viewing the page source!
  fetch("https://api.sequenzy.com/api/v1/...", {
    headers: { Authorization: "Bearer sk_live_..." }, // DANGEROUS!
  });
}

Use HTTPS Only

Always use https:// when making API requests. The API does not accept unencrypted HTTP connections.

Monitor Usage

Regularly check the “Last used” timestamp for your API keys. If you see unexpected activity, rotate the key immediately.

​Authentication

​Choose the right API key

​Getting Your API Key

​Using Your API Key

​Example Request

​Select a workspace with an account key

​Example in Code

​API Key Best Practices

​1. Use Environment Variables

​2. Create Separate Keys for Each Environment

​3. Rotate Keys Periodically

​4. Use the Smallest Permission Set

​5. Never Commit Keys to Git

​6. Use Secrets Management in Production

​Authentication Errors

​401 Unauthorized

​Common Mistakes

​Managing API Keys

​View Active Keys

​Delete a Key

​Security Recommendations

​Server-Side Only

​Use HTTPS Only

​Monitor Usage

​Next Steps

API Reference

Quick Start

Authentication

Choose the right API key

Getting Your API Key

Using Your API Key

Example Request

Select a workspace with an account key

Example in Code

API Key Best Practices

1. Use Environment Variables

2. Create Separate Keys for Each Environment

3. Rotate Keys Periodically

4. Use the Smallest Permission Set

5. Never Commit Keys to Git

6. Use Secrets Management in Production

Authentication Errors

401 Unauthorized

Common Mistakes

Managing API Keys

View Active Keys

Delete a Key

Security Recommendations

Server-Side Only

Use HTTPS Only

Monitor Usage

Next Steps