Skip to main content

​
JWT Bearer token

Most CauseFlow API endpoints require a JWT Bearer token. Include the token in the Authorization header of every request: 
Authorization: Bearer <your-jwt-token>

​
JWT claims structure

CauseFlow JWTs include the following standard and custom claims: 
{
  "sub": "usr_01HX9VTPQR3KF8MZWBYD5N6JCE",
  "email": "alice@acme.org",
  "tenant_id": "ten_01HX9VTPQR3KF8MZWBYD5N6JCE",
  "roles": ["operator"],
  "iss": "https://auth.causeflow.ai",
  "aud": "https://api.causeflow.ai",
  "exp": 1711929600
}
ClaimTypeDescription
substringUnique user identifier
emailstringUser email address
tenant_idstringTenant the user belongs to
rolesstring[]RBAC roles assigned to the user (admin, owner, operator, viewer)
issstringToken issuer — always https://auth.causeflow.ai
audstringIntended audience — always https://api.causeflow.ai
expnumberUnix timestamp when the token expires

​
Example: authenticated request

curl https://api.causeflow.ai/v1/incidents \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

​
API key authentication

API keys are used for webhook endpoints. Include your API key in the X-API-Key header: 
X-API-Key: cflo_live_sk_01HX9VTPQR3KF8MZWBYD5N6JCE
API keys are prefixed with cflo_ and can be created in Settings → API Keys in the CauseFlow dashboard.

​
Webhook HMAC signature

When CauseFlow delivers a webhook to your endpoint, every request includes an HMAC-SHA256 signature in the X-Webhook-Signature header. Verify this signature to confirm the request originated from CauseFlow. 
X-Webhook-Signature: sha256=a3f1b2c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2
The signature is computed as HMAC-SHA256(webhook_secret, raw_request_body), encoded as a lowercase hex string prefixed with sha256=.

​
Verifying the signature

#!/bin/bash
BODY='{"event":"incident.created","incidentId":"inc_01HX9VT"}'
SECRET="whsec_your_webhook_secret"

COMPUTED=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
SIGNATURE="sha256=$COMPUTED"

echo "Computed: $SIGNATURE"
Always verify the HMAC signature before processing webhook payloads. Never skip this step in production.