Authentication

Every /v1 merchant endpoint authenticates with a store API key sent as a bearer token:

Authorization: Bearer tbrn_live_3f1c2b9a7d4e4f889a102c6e5b4d1a90aabbccdd001122

The buyer-facing /v1/checkouts endpoints are the exception: they are deliberately unauthenticated, because they run in the buyer’s browser. Never ship an API key to a page.

Key format

A live key is always tbrn_live_ followed by 48 hexadecimal characters. That is the only accepted shape — anything else fails validation before it reaches the store lookup. The tbrn_live_ prefix exists so that a key leaked into a log, a screenshot or a public repository is recognisable both to a human and to automated secret scanners.

A key is bound to one store. Taberna derives the store from the key, which is why no /v1 endpoint takes a store id — POST /v1/orders creates an order for the key’s store and nothing else.

Scopes

Scopes are chosen when the key is minted and are fixed for its lifetime. To change them, create a new key and revoke the old one.

Scope	What it unlocks
`orders:read`	`GET /v1/orders`, `GET /v1/orders/{id}`
`orders:write`	`POST /v1/orders`, `POST /v1/orders/{id}/expire`
`invoices:read`	`GET /v1/invoices`, `GET /v1/invoices/{id}`, `GET /v1/invoice-templates`
`invoices:write`	`POST /v1/invoices`, `POST /v1/invoices/{id}/void`, `POST /v1/invoices/{id}/send`
`products:read`	`GET /v1/products`, `GET /v1/products/{id}`
`products:write`	`POST /v1/products/{id}/stock`
`webhooks:read`	`GET /v1/webhook-deliveries`
`webhooks:write`	`POST /v1/webhook-deliveries/{deliveryId}/resend`

Notes worth internalising:

Invoice templates read under invoices:read, not a scope of their own — they are invoice authoring material.
webhooks:write is replay only. It lets a key push a failed delivery back into the queue. It does not permit changing where a store’s events are sent; that stays a dashboard action.
Choosing scopes is mandatory. There is no implicit full-access key. An empty scope array, or an unknown scope name, is rejected at key creation.

Grant the minimum. A server that only sells one thing needs orders:write and orders:read — nothing else. Every scope you add is blast radius if the key leaks.

The one endpoint that needs no scope

GET /v1/store — “whoami” — is callable by any valid key, whatever it was granted. Its response includes the calling key’s own scopes array:

{
  "id": "0197f8a0-2222-7bbb-9ddd-4f6e8dac2b35",
  "name": "My Store",
  "image": null,
  "enabledPaymentMethods": ["usdc_base", "sol"],
  "requireCustomerEmail": true,
  "createdAt": "2026-07-01T09:12:44.000Z",
  "slug": "my-store",
  "storefrontEnabled": true,
  "scopes": ["orders:read", "orders:write"],
  "storefrontUrl": "https://my-store.taberna.io"
}

This exists so an integration can discover what it may do without provoking a 403 to find out. Call it at boot, assert the scopes you need, and fail your own startup with a clear message rather than failing a customer’s checkout later. storefrontUrl is the canonical public origin of the store’s storefront (an active custom domain wins over the slug subdomain) and is null while the storefront is unclaimed or switched off.

401 versus 403

The two are not interchangeable and the distinction matters for how your client should react.

401 — bad credential
403 — insufficient scope

Returned for every authentication failure: missing header, malformed header, unknown key, revoked key, expired key.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token"
Content-Type: application/json

{ "error": "Unauthorized" }

The body is always exactly { "error": "Unauthorized" }. The reason is deliberately not disclosed — telling a caller “revoked” rather than “unknown” would confirm to whoever is guessing that a key exists. Never branch on the body.The RFC 6750 challenge in the WWW-Authenticate header is the only signal that distinguishes cases:

Challenge	Meaning
`Bearer realm="api"`	No `Authorization` header at all
`Bearer realm="api", error="invalid_request"`	The header was present but malformed
`Bearer realm="api", error="invalid_token"`	A credential was supplied and failed validation

Returned when the credential is fine but the key was not granted the scope the route requires. There is no WWW-Authenticate header, because re-challenging for a credential would be the wrong instruction.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{ "error": "Missing required scope: orders:write" }

The message names the exact scope, because it is actionable: mint a key that has it.

Retrying a 403 is pointless, and so is re-authenticating. Treat it as a configuration error to surface to an operator — never as a signal to refresh a token, drop the credential, or sign a user out.

Rotation and revocation

Keys are minted, listed and revoked from the dashboard by a store owner.

The raw key is shown once

At creation, and only at creation. Taberna keeps a SHA-256 hash and cannot recover the original. Put it straight into your secret manager.

Rotate by overlap, not by swap

Mint the new key first, deploy it, confirm traffic is flowing on it, then revoke the old one. Because scopes are immutable, a scope change is always a rotation.

Revocation is immediate

A revoked key answers 401 on the next request. So does a key past its optional expiresAt. Keys created without an expiry do not expire.

A key’s lastUsedAt is tracked, so the key list in the dashboard will tell you whether a key you are about to revoke is still receiving traffic.

Handling auth in your client

async function tabernaFetch(path, init = {}) {
	const res = await fetch(`https://api.taberna.io${path}`, {
		...init,
		headers: {
			...init.headers,
			Authorization: `Bearer ${process.env.TABERNA_API_KEY}`,
		},
	});

	if (res.status === 401) {
		// The credential itself is bad. Retrying will not help.
		throw new Error('Taberna API key is missing, revoked or expired');
	}
	if (res.status === 403) {
		// Valid key, missing scope. Surface it — do not retry, do not re-auth.
		const { error } = await res.json();
		throw new Error(`Taberna key lacks a required scope: ${error}`);
	}
	if (!res.ok) {
		const body = await res.json();
		throw new Error(body.error ?? `Taberna request failed (${res.status})`);
	}

	return res;
}

Get started

Charging a customer

Getting paid

Reference

Key format

Scopes

The one endpoint that needs no scope

401 versus 403

Rotation and revocation

Handling auth in your client

​Key format

​Scopes

​The one endpoint that needs no scope

​401 versus 403

​Rotation and revocation

​Handling auth in your client

Key format

Scopes

The one endpoint that needs no scope

401 versus 403

Rotation and revocation

Handling auth in your client