Arenza is now part of the OpenAI Partner Network 🎉
arenza
Free audit
Chapters

API Keys

Use an API Key to let your backend send configured business events to Arenza. This guide explains the three values you need, where to get them, and where they go in a request.

1. Get the website ID

Log into Portal → AI Integrations, select the intended brand, and copy Website install ID. It starts with arz_pub_.

Use this value for website_install_id in the request URL. It selects the website/brand connection that should receive the event. It is public: knowing this ID does not authorize someone to send server events.

2. Create the secret Key

  1. In the same Portal, open Personal Access Tokens.
  2. Click New token, enter a name and select Write to send events. Read alone cannot send events.
  3. Click Create token and copy the arn_pat_… value. It is shown only once. This is the value called API_KEY below.

The Key authorizes your backend's request. Store it in your backend's secret manager and load it there when sending. Never put it in browser code, a source repository or a URL. If lost, create a replacement; the old plaintext cannot be recovered. Log into the Portal to create or revoke Keys. The interface has no Key editing or expiry-date setting.

Before sending: the Key must have Write permission and access to the target brand. The connection must already have server events configured, and the event type must be allowed. Creating a Key or installing the SDK does not configure these events or create a billing contract.

3. Generate an event deduplication ID

webhook-id is the deduplication ID for this event. Your backend generates and saves one UUID for each event. Reuse that same UUID when retrying the same event; generate a new UUID for a different event.

It is not the visitor ID stored in a Cookie. The visitor ID is arenza_visitor_id, saved in a browser Cookie by the SDK and meaning “which visitor produced the event”: the frontend reads it with getVisitorId() and passes it to your backend, which puts it in the request body as attribution.visitor_id. webhook-id means “which event this is” — one visitor can produce several events, all sharing the same visitor ID while each event has its own webhook-id.

A UUID is a unique identifier in a standard format, not an arbitrary name. For example, Python's uuid module generates one with str(uuid.uuid4()).

This value identifies the event, not the sender's permission. It is not a credential, does not come from the Portal, and is not a server receipt.

4. Put the values in the request

Replace {website_install_id} with the public arz_pub_… ID, <API_KEY> with the secret arn_pat_… Key, and <UUID> with your saved event deduplication UUID. Keep Bearer before the Key. Content-Type: application/json tells the server that the request body is JSON.

The block below shows only the method, path and headers: it is not a complete request. For body fields and complete Python/Go examples, follow Server events. Send from your backend to https://api.arenza.ai, not from a browser.

POST /api/v1/billing-events/{website_install_id}
Authorization: Bearer <API_KEY>
Content-Type: application/json
webhook-id: <UUID>

Rotate or revoke

Create a new Key, update your backend and verify requests. Then click Revoke for the old Key in the same token list. Subsequent requests using the old Key will be rejected.

Check the response

  • 401: the Key is missing, invalid or revoked.
  • 403 insufficient_scope: Write is missing.
  • 404: the connection is unavailable or the Key lacks brand access.
  • 422 server_event_not_configured: the installation ID is measurement-only, without server events configured.
  • 422 event_handle_not_allowed: the event type is not allowed.

202 means accepted or queued, not that the business outcome, attribution or billing has completed. More responses are in the API reference.

A Key works only with endpoints that support it, not every Arenza API. To connect an AI assistant, follow MCP Server, which uses OAuth instead of this Key.