> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the Sequenzy API

# Authentication

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, while viewer memberships remain read-only
even when the key has a broader preset.

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

1. Log in to your [Sequenzy dashboard](https://www.sequenzy.com/dashboard)
2. Open **Workspace Settings → API Keys** for a workspace key, or **Account
   Settings → API Keys** for an account key
3. Click **Create API Key**
4. Give your key a descriptive name (e.g., "Production Backend", "AI Drafting Agent")
5. Choose a permission preset or custom permissions
6. Copy and securely store your key—it won't be shown again

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

## Using Your API Key

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

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

### Example Request

```bash theme={null}
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:

```bash theme={null}
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

```javascript theme={null}
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:

```javascript theme={null}
// 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:

1. Create a new API key
2. Update your application to use the new key
3. 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.

### 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 and draft content without sending live emails or deleting records
* **AI drafting** for agents that can inspect data 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.

### 5. Never Commit Keys to Git

Add your environment file to `.gitignore`:

```bash theme={null}
# .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

```json theme={null}
{
  "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:

1. Go to the API Keys page where the key was created
2. Find the key you want to delete
3. Click **Delete**
4. Confirm the deletion

<Warning>
  Deleting a key immediately invalidates it. Any requests using that key will
  start failing.
</Warning>

## Security Recommendations

### Server-Side Only

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

```javascript theme={null}
// 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.

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore all available endpoints
  </Card>

  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Send your first email in 5 minutes
  </Card>
</CardGroup>