Authentication

Overview

All Delivr.ai API calls require authentication. Most endpoints accept a Bearer JWT token; some also accept an API key via the X-Api-Key header. Pixel tracking endpoints are public and require no authentication.

Step 1: Create an Account

Retrieve your invite to Delivr.ai via email or sign up at https://app-v2.delivr.ai/sign-up and verify your email.

Step 2: Login (Get JWT Token)

curl -X POST https://apiv3.delivr.ai/auth/v1/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "YOUR_EMAIL",
    "password": "YOUR_PASSWORD"
  }'

Response (200 OK)

{
  "user_id": "c5553b3d-22db-...",
  "organization_id": "bc638318-dba9-...",
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Save these values:

Error Responses

Step 3: Create an API Client (Optional)

API clients provide a stable api_key for programmatic access instead of using your JWT directly.

curl -X POST https://apiv3.delivr.ai/client/v1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Client"
  }'

Response (201 Created)

{
  "client_id": "5f56c253-5e18-...",
  "api_key": "dlvr_74ce9b3f761368ede79ec2db...",
  "api_secret": "99ebda82ac1cdb68f8a9ece801051e4c...",
  "created_at": "2026-01-01 10:00:00"
}

Save your api_key and api_secret now. The secret cannot be retrieved later.

List Your API Clients

curl https://apiv3.delivr.ai/client/v1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "clients": [
    {
      "client_id": "5f56c253-5e18-...",
      "name": "My API Client",
      "status": "active",
      "api_keys": [
        {
          "key_id": "71a23beb-47f4-...",
          "key_prefix": "dlvr_74ce9b3...",
          "status": "active",
          "created_at": "2026-01-01 10:00:00"
        }
      ],
      "created_at": "2026-01-01 10:00:00"
    }
  ],
  "total": 1
}

The list endpoint shows a truncated key_prefix, not the full key. The full api_key and api_secret are only returned at creation time.

Delete an API Client

curl -X DELETE https://apiv3.delivr.ai/client/v1/YOUR_CLIENT_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response (200 OK)

{
  "message": "API client deleted successfully."
}

Step 4: Using Your API Key

After creating an API client in Step 3, use the api_key value (prefixed with dlvr_) as the X-Api-Key header on supported endpoints:

curl https://apiv3.delivr.ai/api/v1/events?pixel_id=YOUR_PIXEL_ID&start_ms=1700000000000&end_ms=1700090000000 \
  -H "X-Api-Key: dlvr_74ce9b3f761368ede79ec2db..."

The API key is validated at the gateway level, so any endpoint that accepts X-Api-Key will work without a JWT. See the table below for which APIs support this method.

Authentication Methods by API

Note: APIs on apiv3.delivr.ai use the JWT from Step 2 (POST /auth/v1/login). APIs on api.delivr.ai/public/core use a different login endpoint -- see Public API Authentication below.

Public API Authentication

The Platform Management API for managing organizations, projects, pixels, and API credentials runs on a different base URL and uses its own login endpoint.

Base URL: https://api.delivr.ai/public/core

Login

curl -X POST https://api.delivr.ai/public/core/auth/issue \
  -H "Content-Type: application/json" \
  -d '{
    "email": "YOUR_EMAIL",
    "password": "YOUR_PASSWORD"
  }'

Response (200 OK)

{
  "response": {
    "user_id": "c5553b3d-22db-...",
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Use this token as a Bearer token on all api.delivr.ai/public/core endpoints:

curl https://api.delivr.ai/public/core/api/organization/get \
  -H "Authorization: Bearer YOUR_PUBLIC_API_TOKEN"

The Public API token does not include an organization_id in the response. Use it for platform management operations (organizations, projects, pixels, apps).

Next Steps

• Account Setup -- Create your first project (required before using Events or Audiences)
• On-Domain Events API -- Create a pixel and query visitor events
• Intent Audiences API -- Create intent-based audiences