Authentication

Unif uses bearer tokens. There is no OAuth flow, no request signing and no session to maintain.

curl https://api.unif.dev/v1/me \
  -H "Authorization: Bearer unif_sk_live_8f3c1a9e4b2d8065f1a3c7e9b5d2408f"

A missing, malformed or revoked key returns 401 with an authentication_error. Unif never falls back to an anonymous mode.

Key format

Prefix	Environment	Behavior
`unif_sk_live_`	Live	Queries real data and consumes credits.
`unif_sk_test_`	Sandbox	Returns fixture data, consumes nothing.

The prefix is deliberately greppable. Secret scanners can match unif_sk_ and catch a key before it reaches a public repository.

Scope

A key is bound to exactly one workspace. It cannot read another workspace’s lists, jobs or trackers, and 404 — not 403 — is what you get for an object outside your workspace, so key probing reveals nothing about what exists. Within a workspace, every key carries the same permissions. Separate keys per service give you independent revocation and a clean read of the usage ledger, not narrower access.

Issue one key per deployed service — api-prod, etl-nightly, analytics-notebook. When one leaks you roll one key, and the ledger tells you which service spent what.

Storing keys

Keep them out of source control

Use environment variables or a secret manager. Never a config file that ships, and never the client side — a key in a browser or mobile binary is a public key.

Proxy browser traffic

If a frontend needs Unif data, call Unif from your own backend and forward the result. The API sets no CORS headers for a reason.

Rotate on a schedule

Create the new key, deploy it, confirm traffic has moved on the ledger, then revoke the old one. Both keys work during the overlap, so rotation needs no downtime.

Verifying a key programmatically

GET /v1/me is cheap, free of credit cost and safe to call on boot as a health check.

import os, requests

def check_unif_key() -> dict:
    resp = requests.get(
        "https://api.unif.dev/v1/me",
        headers={"Authorization": f"Bearer {os.environ['UNIF_API_KEY']}"},
        timeout=10,
    )
    if resp.status_code == 401:
        raise RuntimeError("UNIF_API_KEY is missing, malformed or revoked")
    resp.raise_for_status()
    return resp.json()

The response tells you the environment and the entitled channels, which makes it a useful guard against the classic mistake of pointing a staging deployment at a live key.

Revocation

Revoking a key from the dashboard takes effect within seconds. In-flight requests complete; everything after fails with 401. Revocation is not reversible — issue a new key instead.

If you believe a key has leaked, revoke first and investigate second. Check GET /v1/usage/events afterwards for calls you cannot account for.

Getting started

Core concepts

Workflows

Guides

Platform

Release notes

Authentication

Key format

Scope

Storing keys

Verifying a key programmatically

Revocation

​Key format

​Scope

​Storing keys

​Verifying a key programmatically

​Revocation

Key format

Scope

Storing keys

Verifying a key programmatically

Revocation