> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.orbitdev.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Advertising API Overview: Auth, Actions, and Idempotency

> Learn how to use the Orbit Advertising API Edge Function. Covers authentication models, CORS, security rules, idempotency, and the two supported actions.

The Advertising API is a public Edge Function that handles click tracking and conversion reporting for Orbit Audience Engine. It is hosted at your Orbit Functions instance.

## Base URL

```text theme={"dark"}
https://<your-orbit-functions-host>/functions/v1/advertising-api
```

Replace `<your-orbit-functions-host>` with your actual Orbit Functions host.

## Two actions

The Advertising API supports two query actions:

| Action | Method | Purpose |
| - | - | - |
| `click` | GET | Track a click from an impression token |
| `conversion` | POST | Report a conversion with advertiser authentication |

## Authentication models

<Accordion title="Opaque impression token (clicks)">
  Click requests use a 256-bit opaque impression token passed in the query string. The token is hashed with SHA-256 before storage or validation. Raw tokens are never stored.
</Accordion>

<Accordion title="x-advertiser-token (conversions)">
  Conversion requests require the `x-advertiser-token` header. Tokens are stored as SHA-256 hashes. Never send service-role keys to clients.
</Accordion>

## CORS and security

Production CORS uses the comma-separated `ORBIT_APP_ORIGINS` allowlist. The Edge Function is public because clicks use signed opaque tokens and conversions use hashed advertiser tokens. All billing RPCs are executable only by `service_role`.

## Idempotency

Conversion requests accept an `idempotency-key` header. Duplicate `external_id` values or idempotency keys return an accepted duplicate response without a second charge.

## Never expose service-role keys

Service-role keys are for server-side use only. Never include them in client-side code, mobile apps, or browser requests.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.