Authentication

Every UMAP360 API request is authenticated with an API key, passed as a Bearer token in the Authorization header:

Authorization: Bearer uk_live_YOUR_KEY

The base URL for all endpoints is your project's edge-function host:

https://YOUR_PROJECT_REF.supabase.co/functions/v1

You'll find both the exact host and your keys in the dashboard under Settings → API Keys.

Key types

UMAP360 issues three kinds of key, each scoped to a different job. The prefix tells you what a key can do:

Type	Prefix	Can do
Write	`uk_live_`	Send events, create profiles
Read	`uk_read_`	Read events and profiles
Admin	`uk_admin_`	Full access, including key management

Key types are not hierarchical: a write key satisfies only write operations, a read key only read operations — only an admin key satisfies all three. A write key can't read profiles, and a read key can't ingest events.

Keeping keys safe

Write keys are public; read & admin keys are not

A write key is designed to be embedded in a browser or mobile app — it can only send events, never read your data. Read and admin keys can access your data and account, so treat them like passwords: keep them on your server, never ship them to a client, and never commit them to source control.

Rotate a key from Settings → API Keys if it's ever exposed; the old key stops working immediately.
Scope down wherever you can — if a server only needs to read profiles, give it a read key, not an admin key.
The API is served only over HTTPS — send keys over TLS, never in plaintext.
Keys are hashed at rest (SHA-256): UMAP360 stores only the hash, never the raw key — so a key is shown once at creation and can't be recovered later (rotate if you lose it). The Bearer wire format is unchanged.

Which key each endpoint needs

Endpoint	Key
`POST /v1-batch` — ingestion	write (or admin)
`POST /v1-consent` — record consent	write (or admin)
`GET /v1-consent` — read consent	read (or admin)
`GET /v1-profiles*` — Profiles API	read (or admin)
`POST /v1-profiles/merge`	admin

Per-key restrictions (advanced)

A key can optionally be restricted further:

IP / Origin allowlist — a key can be locked to specific client IPs and/or request Origins. A request from a non-allowed IP returns 403 with code: "ip_not_allowed"; a non-allowed Origin returns 403 with code: "origin_not_allowed". An empty allowlist (the default) allows all, so existing keys are unaffected.
Per-key rate cap — a key can carry a rate limit that tightens (never raises) the endpoint's default per-minute limit.

Enforced, but not yet self-serve

These per-key restrictions are enforced at the edge today, but there is no dashboard UI to configure them yet — they're set directly on the key record. If you want a browser-embedded write key locked to your own domain, ask us to set an Origin allowlist until the Settings UI ships.

Authentication errors

Status	Meaning	Fix
`401`	Missing or invalid `Authorization`	Add `Authorization: Bearer <key>`, check the key isn't revoked
`403`	Wrong key type for the endpoint	Use a write (or admin) key for ingestion, a read (or admin) key for the Profiles API. The message names the required type, e.g. "Insufficient permissions: this operation requires a `write` or admin key."

See Errors & rate limits for the complete list of status codes and the error response shape.

Last updated 2026-06-10