Authentication

The Ours Privacy Ingest API authenticates each request with a source API key. Unlike the Platform API, the key is sent as a token field in the request body, not in an Authorization header.

{
  "event": "Purchase",
  "userId": "user123",
  "token": "YOUR_API_KEY"
}

Creating an API Key

The Ingest API key is issued when you add a server-side source to your account.

1. Go to Sources → Add Source in your Ours Privacy dashboard
2. Under the API category, select a source (for example, Server API, or a language-specific option such as Python API or Node.js API)
3. Open the new source's settings and copy the API Key. You'll also find the API endpoint and an example curl request for the /track endpoint.

Important: Treat your API key like a password. Store it in a secrets manager, environment variable, or encrypted configuration. Never commit it to source control.

Identifying the Visitor

Authentication associates a request with your account; you still need to tell the API which visitor an event belongs to. Include at least one of these identifiers in every request:

• userId: the Ours Privacy Visitor ID stored on your web properties. When present, it's used directly with no lookup.
• externalId: your own identifier for a visitor. Ours Privacy looks up a matching visitor in your account, or creates one if none exists.
• email: an email address, used as a fallback lookup when neither userId nor externalId is provided.

Use the same identifier across your web and server implementations so events resolve to one visitor.

Test Mode

Each source also has a Test Mode API key for validating an integration without dispatching events to your destinations.

1. Open your source's settings and turn on the Test Mode toggle
2. Copy the Test Mode API key it reveals, then send requests with it in place of your live key

Events sent with the Test Mode key are processed and stored in Recent Events as test events, but are never forwarded to configured destinations. Swap in your live key when you're ready to dispatch.

Error Handling

Rotating a Key

Rotate keys by standing up a fresh source and migrating to it, so no events are lost in the transition:

1. Create a new source. Go to Sources → Add Source and add another server-side source to generate a new key while the existing one stays active.
2. Update your integration. Point your backend at the new key.
3. Monitor event flow. Confirm events arrive under the new source in Recent Events and the volume matches expectations.
4. Retire the old source. Once everything flows through the new key, deactivate and delete the old source.

Next Steps

• Quickstart: make your first API call.
• Ingest API Overview: endpoints and key concepts.