Authentication

Personal access tokens (PATs)

Non‑browser callers — scripts, integrations, and the AI Toolkit — authenticate with a personal access token. A PAT is created by a provider and is scoped to that provider's company.

Create one in the provider portal under Settings → API tokens (/vendor/settings/api):

1. Give the token a name (e.g. ci, claude-toolkit).
2. Pick the scopes it should carry.
3. Optionally set an expiry.
4. Copy the token when it's shown — it is displayed only once. We store only a hash; if you lose it, revoke it and create a new one.

Use it as a bearer token on every request:

Authorization: Bearer iot_pat_xxxxxxxxxxxxxxxxxxxxxxxx

Scopes

Tokens carry explicit scopes. Read scopes:

Write scopes:

See Managing products and Managing your storefront for the write endpoints.

How scopes are enforced

• Reads: any valid token may issue GET requests for its company. Read scopes are advisory today (not enforced per-endpoint).
• Writes are fail-closed and scope-gated: a non-GET request is allowed only on an endpoint that explicitly accepts that write scope and when your token holds it. Every other write endpoint — including company settings, banking, team, and payments — is unreachable by any token, even one with a write scope. A token without the required write scope gets 403.

A token never grants more than the scopes you select. store:write and theme:write are reserved for a later release.

Tenant scoping

A PAT resolves to exactly one company. Every request is evaluated against that company:

• Reads return only that company's data.
• A request naming a different company id returns 403.

This is the same tenant isolation the browser session enforces — a token can never read across company boundaries.

Revoking

Revoke a token any time from Settings → API tokens. Revocation is immediate; the next request with that token fails. Revoke and re‑issue if a token is ever exposed.