Authentication

Datafly Signal uses different authentication mechanisms depending on the context: JWT tokens for the Management API, pipeline keys for browser-side event collection, and HMAC signatures for server-side event submission.

Authentication Methods

JWT Authentication (Management API)

The Management API authenticates requests using JWT (JSON Web Tokens). Users log in with email and password to receive an access token and refresh token.

Flow

1. POST /v1/admin/auth/login  →  { access_token, refresh_token }
2. Include in requests:  Authorization: Bearer {access_token}
3. When expired:  POST /v1/admin/auth/refresh  →  new { access_token, refresh_token }

Token Details

Security Properties

• Short-lived access tokens (15 minutes) limit the window of exposure if a token is compromised.
• Refresh token rotation — each refresh request invalidates the previous refresh token and issues a new one. If a rotated-out token is reused, all tokens for that user are revoked.
• Token signing uses HMAC-SHA256 with a server-side secret (JWT_SECRET). Tokens cannot be forged without the secret.

For full API details, see Management API Authentication.

Pipeline Key Authentication (Browser Events)

Datafly.js authenticates event submissions using a pipeline key — a unique identifier assigned to each source. The pipeline key is included in the script tag or SDK initialization and sent with every event request.

Pipeline Key Format

dk_live_abc123...    (production)
dk_test_xyz789...    (testing)

How It Works

1. The Datafly.js script reads the pipeline key from the data-pipeline-key attribute:

   <script src="https://data.example.com/d.js" data-pipeline-key="dk_live_abc123"></script>

2. Every event request includes the pipeline key in the Authorization header:

   Authorization: Bearer dk_live_abc123

3. The Ingestion Gateway validates the pipeline key against PostgreSQL (cached in Redis).

4. If the pipeline key is invalid, revoked, or missing, the gateway returns 401 Unauthorized.

Security Properties

• Pipeline keys are public — they are visible in the page source. They authenticate which source an event belongs to, not who is sending it.
• Pipeline keys are scoped to a single source. A key from one source cannot be used with another.
• Pipeline keys can be revoked by deleting the source or generating a new key, immediately blocking all events using the old key.
• The gateway enforces CORS based on the source’s configured domains. Even with a valid pipeline key, events are rejected if the Origin header does not match.

HMAC-SHA256 Authentication (Server-Side Events)

For server-side event submission (from your backend to the Ingestion Gateway), requests are authenticated using HMAC-SHA256 signatures.

How It Works

1. Your server computes an HMAC-SHA256 signature of the request body using the source’s server secret (available in the Management UI under Source settings):

   signature = HMAC-SHA256(server_secret, request_body)

2. Include the signature in the request header:

   X-Datafly-Signature: sha256=<hex-encoded-signature>

3. The Ingestion Gateway recomputes the signature and compares it. If the signatures match, the request is authenticated.

Example

# Compute the signature
BODY='{"type":"track","event":"Order Completed","userId":"user_123","properties":{"total":99.99}}'
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "your_server_secret" | awk '{print $2}')
 
# Send the request
curl -X POST https://data.example.com/v1/t \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dk_live_abc123" \
  -H "X-Datafly-Signature: sha256=$SIGNATURE" \
  -d "$BODY"

Security Properties

• The server secret is private and never exposed in client-side code.
• HMAC signatures prove that the request body has not been tampered with in transit.
• Server-side events bypass CORS checks (there is no browser Origin header).

SSO Integration (Planned)

Datafly Signal will support federated authentication for the Management API via:

• SAML 2.0 — for enterprise identity providers (Okta, Azure AD, OneLogin)
• OpenID Connect — for OAuth 2.0-based identity providers (Google Workspace, Auth0)

When enabled, users will authenticate through their organisation’s identity provider instead of email/password. JWT tokens will still be issued by the Management API after SSO authentication.