Authentication

Overview

Delivr.ai data APIs (events, audiences, taxonomy, identity lookup) authenticate with an organization API key + secret pair, created from the dashboard.

X-Api-Key: dlvr_...
X-Api-Secret: ...

There is one supported way to create keys: the dashboard at https://app.delivr.ai/{org_id}/settings/api-keys. The dashboard is the only place that displays the secret half. We do not recommend (and are phasing out) JWT-based programmatic key creation.

First time here? Your Delivr contact (sales or support) creates the organization and invites your first user(s). Once you accept the invite and sign in to app.delivr.ai, everything from API keys to project settings to inviting teammates is self-serve.

Base URL: https://apiv3.delivr.ai

Create your API key in the dashboard

The fastest, safest way to get a working key + secret pair is to create one through the UI.

1. Sign in at app.delivr.ai and switch to the organization you want the key to belong to.

2. Open Settings > API keys. The direct link is https://app.delivr.ai/{org_id}/settings/api-keys (replace {org_id} with your organization ID).

3. Click Create key and give it a descriptive name (for example, "Production export job" or "Hubspot sync").

4. In the confirmation dialog, copy both values into your secrets manager before closing it:

   Value	Format	Where to use it
   api_key	dlvr_ prefix	X-Api-Key header on every request
   api_secret	hex string	X-Api-Secret header on every request

The full api_secret is shown once, at creation time. If you close the dialog without saving it, you'll need to delete the key from the same page and create a new one. The list view shows only the key prefix; it cannot reveal the secret again.

Keys are scoped to the organization that owns them. Anyone with both halves can call the API as that organization, so treat the pair like a password: rotate on suspected leak, never commit either value to source control. Use the Revoke action in the same dashboard page to retire a key.

Make your first authenticated request

Once you have the pair, every request to apiv3.delivr.ai carries both headers. The two-header pattern works on every data endpoint (events, audiences, taxonomy, identity lookup).

curl "https://apiv3.delivr.ai/api/v2/events_schema?source=pixel" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

Response (200 OK)

{
  "fields": [
    { "name": "event_id", "data_type": "Utf8", "nullable": false },
    { "name": "event_type", "data_type": "Utf8", "nullable": false },
    { "name": "ts_millis", "data_type": "Int64", "nullable": false },
    { "name": "resolved", "data_type": "Boolean", "nullable": true }
  ]
}

If you see 401 {"error":"Invalid API key"}, double-check that you copied the full dlvr_-prefixed value. If you see 401 {"error":"Invalid API secret"}, the secret half does not match the key on file. Create a new pair from the dashboard.

Why both halves matter

A leaked api_key on its own is not enough to call the API. The platform compares the supplied api_secret against a stored hash on every request, in constant time, and rejects mismatches with 401. Pair-based auth means:

• You can rotate the secret without re-issuing the key (less downstream config churn).
• Keys can be safely surfaced in logs or dashboards; the secret stays out of those code paths.
• Per-key access logs show exactly which credential made each call.

If your organization has secret_required enabled (default for new keys), a request that omits X-Api-Secret is rejected with 401 {"error":"API secret is required"}. Older keys may still accept secret-less calls during migration, but every new integration should send both headers.

Per-endpoint headers

A note on legacy auth methods

If you have older integrations that use a JWT (obtained from POST /auth/v1/login with an email and password) or use only the X-Api-Key header without a secret, those continue to work for now. Both patterns are on the deprecation path. Move them to dashboard-created key + secret pairs at your next maintenance window. We will publish a removal timeline before disabling either path.

Next steps

• On-Domain Events API: query pixel events with the v2 endpoint
• Account Setup: create a project and pixel
• Intent Audiences API: build intent-based audiences