Authentication

Overview

Application API endpoints generally require authentication via a Bearer token in the Authorization header:

Authorization: Bearer <token>

The credential options below include tenant API keys, embedded session tokens, Cognito ID tokens, and the operator admin key. API keys support integrations on endpoints that accept them.

API Keys (recommended for integrations)

API keys are long-lived, tenant-scoped tokens designed for machine-to-machine integrations — Zapier, Make, n8n, custom backends, cron jobs, and anything that calls the API without a human in the loop.

Creating a key

1. Open the Signals dashboard
2. Navigate to Settings → API Keys
3. Click Create API Key
4. Enter a descriptive label (e.g., "Zapier Production", "CRM Sync", "Monitoring Script")
5. Copy the key immediately — it is shown only once

Keys follow the format wfsk_<tenant_prefix>_<random>.

Using a key

Include it as a Bearer token:

curl -X POST -H "Content-Type: application/json" -d '{"message":"Please contact me"}' -H "Authorization: Bearer wfsk_acme_abc123..." \
  https://api.warpflow.ai/api/v1/webhook/zapier/acme

Credential capabilities

Tenant API keys can access same-tenant endpoints protected by tenant scope alone, including basic contact CRUD, conversations, email send, aliases GET, and tasks. They do not satisfy manager or admin role guards: configuration writes, Signal Guard, SMS filters, and email settings writes require an appropriate Cognito ID token or the operator admin key. Custom events require a source webhook key; the Telnyx assistant tool uses an assistant secret; other provider webhooks verify provider signatures. Health, public documentation, and /api/v1/public/* use no Bearer token (public submissions use Turnstile and an IP limit). /api/v1/sessions also accepts a bare location_id without a credential; this current behavior is tracked in #2237. The direct tenant_id session flow requires an admin key or an authorized Cognito token.

Managing API keys and outbound webhook subscriptions (creating, listing, rotating, or revoking a key, and creating, listing, deleting, or testing a webhook subscription) is restricted to tenant admins and above: a tenant admin or superuser Cognito principal, or the operator admin key. A tenant API key is an integration principal: it carries no role, so it is not accepted on these management surfaces even for the tenant it belongs to. A key cannot mint, rotate, or revoke itself or any other key, and cannot register or remove a webhook subscription.

Limits

• 3 active keys per tenant — encourages intentional key management
• Last-used tracking is debounced; last_used_at is not updated on every request
• Keys are tenant-scoped — a key for tenant A cannot access tenant B's data

Rotating a key

Key rotation generates a new key while keeping the old one active for a grace period:

1. Go to Settings → API Keys
2. Click Rotate on the key you want to replace
3. Copy the new key
4. Update your integrations to use the new key
5. The old key enters deprecated status and remains valid for 72 hours
6. After 72 hours, the old key is no longer accepted

This lets you update integrations without downtime.

Revoking a key

Revocation is immediate and permanent. Once revoked, the key cannot be re-activated. Use this if a key is compromised or no longer needed.

HIPAA tenants

The product restricts tenant API-key creation for HIPAA-enabled tenants. This is a product policy, not a general legal requirement to use OAuth2. For supported programmatic access, use tenant-scoped session tokens created via the admin API or an appropriate Cognito ID token. Email remains unavailable; another credential does not bypass its restriction.

Session Tokens (for embedded UIs)

Session tokens are short-lived, tenant-scoped tokens created programmatically. Use them when embedding Warpflow functionality in your own UI or when you need temporary access without distributing a long-lived key.

# Create a session token using the authenticated direct tenant_id flow
curl -X POST https://api.warpflow.ai/api/v1/sessions \
  -H "Authorization: Bearer ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "acme"}'

Response (200):

{
  "token": "eyJzdWIiOiJhY21lIiwibG9jIjpudWxsLCJpYXQiOjE3NzE3ODA2MDAwMDAsImV4cCI6MTc3MTc4NDIwMDAwMH0.k3Jq7f8XyR2mNvB0aL9pQwZs1TcHdEfGiJkLmNoPqRs",
  "tenant_id": "acme",
  "expires_at": 1771784200000
}

Properties:

• 1-hour TTL. expires_at is Unix epoch milliseconds, not an ISO-8601 string.
• Tenant-scoped, to the one tenant you asked for. It cannot reach another.
• Agent-level rights. A session token is treated as the lowest privilege level: it can do what an agent can do, and is refused anything needing manager, admin or superuser.
• The token is two base64url segments joined by a dot. It resembles a JWT and is not one—do not hand it to a JWT library, and do not expect a sess_ prefix.
• Use it in the same Authorization: Bearer <token> header as an API key.

See Sessions in the API reference for the request shape and error codes.

OAuth2 (dashboard login)

The Signals dashboard uses OAuth2 for user authentication. This is handled automatically when you log in to the dashboard — you don't need to manage tokens for API integrations.

If you're building a custom frontend that needs the same user-based auth as the dashboard, contact support for OAuth2 integration guidance.

Which auth method should I use?