Authentication

Overview

Delivr.ai data APIs (events, audiences, taxonomy, identity lookup) authenticate with an API key + secret pair, created from the dashboard. A key is scoped either to your whole organization or to a single project; see Project-scoped API keys.

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://api.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"). Under Scope, keep Organization (every project), or choose one project to create a project-scoped key.

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.

An organization key reaches every project in the organization that owns it; a project-scoped key reaches one project. Anyone with both halves can call the API with that scope, 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 api.delivr.ai carries both headers. The two-header pattern works on every data endpoint (events, audiences, taxonomy, identity lookup).

curl "https://api.delivr.ai/api/v3/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

This table describes an organization key. A project-scoped key reaches fewer of these, and only for its own project; see Project-scoped API keys.

Project-scoped API keys

A project-scoped key is bound to one project when you create it. It uses the same X-Api-Key and X-Api-Secret headers as an organization key, but it reads and writes only its own project's data. Use one to give a client, a team, or a single integration access to one project without exposing the rest of your organization. If you run projects for several clients, issue one key per client.

Create one

In Settings > API keys, click Create key and choose a project under Scope. A project admin creating a key from inside their project gets a key bound to that project; the scope selector is not shown.

The scope is fixed at creation. To change it, revoke the key and create another.

What a project key confines

• Naming another project, or a pixel, campaign or record that belongs to another project, is refused. The status code depends on the API; see the table below.
• An endpoint a project key cannot use answers 403, with a message saying the endpoint is not available to a project-scoped API key.
• Usage on the events API, identity lookup, the intent API and audience downloads is attributed to the key's project.
• A project key is held to its project's budget as well as your organization's, on every route that bills. When the organization's budget refuses a project key, the 402 omits the organization's spend and budget figures. See Project budgets.

Where a project key works

Not available to a project key (403): the organization itself (/api/v1/organization), organization members (/api/v1/organization/user*), creating, listing and deleting projects, and project members (/api/v1/project/user*). Use an organization key for these.

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