Authentication

Overview

All Warpflow API endpoints require authentication via a Bearer token in the Authorization header:

Authorization: Bearer <token>

There are three token types. For most integrations, API keys are what you want.

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 wf_<tenant_id>_<random>.

Using a key

Include it as a Bearer token:

curl -H "Authorization: Bearer wf_acme_abc123..." \
  https://api.warpflow.ai/api/v1/tenants/acme/conversations

Limits

• 3 active keys per tenant — encourages intentional key management
• Audit tracked — every request updates the key's last_used_at timestamp
• 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 automatically revoked

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

API keys are disabled for HIPAA-enabled tenants. HIPAA compliance requires OAuth2 authentication (Cognito). If you need programmatic access on a HIPAA tenant, use session tokens created via the admin API.

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 (requires admin API key)
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": "sess_acme_e8f2a1b3c4d5...",
  "tenant_id": "acme",
  "expires_at": "2026-02-22T15:30:00Z"
}

Properties:

• 1-hour TTL (see expires_at in the response)
• Tenant-scoped (same as API keys)
• Created via the /sessions endpoint using an admin API key
• Use the same Authorization: Bearer <token> header with the returned token value

Cognito JWT (dashboard login)

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

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

Which auth method should I use?