# Authentication: key and permissions

**Status:** current · **Verified:** 2026-10-25, checked against token issuance,
passport, scope registry and guards; no live credentials used
**Owner:** Vizen API documentation · **Serves:** `GET /docs/authentication`

## 1. Obtain a key

Open the shop cabinet → **API access** at
[admin.vizen.shop/api-access](https://admin.vizen.shop/api-access) and issue a
personal API token for the task. Choose the required permissions, contour and
expiry. The plaintext key is shown **once**; the server stores its hash.
Issuing and revoking keys are cabinet actions, not operations delegated to a PAT.

Choose the narrowest permissions and a finite expiry for temporary work.
Sensitive permissions require the shop owner or administrator. The generated
[scope reference](/docs/scopes.json) identifies them; do not infer sensitivity
from a preset name. Existing keys do not automatically acquire newly added rights.

## 2. Authenticate and read the passport

API base: `https://api.vizen.shop`. Send this header on authenticated requests:

```http
Authorization: Bearer <personal-api-token>
```

Supply the secret through a protected process environment, with shell tracing
and HTTP header logging disabled. With `VIZEN_TOKEN` already supplied securely,
the first request is:

```bash
curl --fail-with-body -sS https://api.vizen.shop/v1/account/token \
  -H "Authorization: Bearer $VIZEN_TOKEN"
```

Read the returned passport **before any write**:

| Field | How to use it |
|---|---|
| `company_id`, `api_base` | Identify the shop and API for this key; a request's `company_id` cannot grant access to another shop. |
| `scopes` | Permissions actually granted to this key. |
| `capabilities` | Supported actions under the key's scopes, contour and applicable role gates. A scope alone does not prove a method is callable. |
| `contour`, `writes_to_live` | `prod` writes to the live shop; `dev` writes supported catalogue/content/file changes to a draft. Tell the owner when changes will be immediately visible. |
| `mode`, `mode_guide` | Follow the actual workflow: `full`, `draft`, `draft_publish`, or a resource-bound `folder_draft`. Publication still needs the owner's instruction. |
| `scopes_denied` | Rights not granted; do not discover them by trial writes. |
| `live_operations_denied`, `prod_sensitive_methods_denied` | Methods a DEV key cannot call; a draft is not a separate copy of all shop operations. |
| `warnings` | Pass the warnings to the owner in full before bulk writes. |
| `store.storefront_url` | Open this address to verify the result; it includes an active custom domain, but a stand's configured base overrides it — if it points at another storefront, report the mismatch. It is not `api_base`. Do not guess the shop URL. |
| `store.currency`, `store.language` | Use the shop's actual settings; pricing rules belong to [Catalogue](/docs/catalogue). |
| `expires_at` | RFC3339 UTC expiry, or `null` for a key without expiry. |
| `guides`, `docs_url` | Continue to documentation relevant to the key. |
| `resource` (when present) | A folder-bound key is limited to the named site folder and DEV draft; see [File storage](/docs/file-storage). |

**The contour belongs to the key.** `dev_header_allowed` is false: neither a
header nor a request parameter switches PROD/DEV. Request an appropriate key
through the owner when the task needs a different contour.

## 3. Check permissions without probing mutations

Use [scopes.json](/docs/scopes.json) for the current scope list, sensitivity and
contour restrictions. Use [OpenAPI](/openapi.json), or a family slice such as
`/openapi.json?scope=catalog`, for each method's requirements. The
[partner projection](/partner/openapi.json) excludes methods closed to PATs.
Do not keep a copied scope matrix in your integration.

For catalogue work with image uploads, request only the needed catalogue and
storage operations; use the passport and method reference to check the exact
rights. Forms and submitted leads have separate permissions: `forms:*` does
not open lead data. Other families are likewise not implied by `catalog:*`.

## 4. Errors and silently ignored assumptions

| Response | Meaning and next action |
|---|---|
| `401` on the passport, `invalid_token` | Missing/wrong key format, or an unknown, revoked or expired key. Check secure secret delivery; ask the owner for a replacement when needed. |
| `403 PAT_SCOPE_MISSING` | A private method needs a scope absent from this key. Read `required_scope` in the error; ask for the required access instead of retrying. |
| `403 PAT_METHOD_NOT_ALLOWED` | The method is closed to personal API tokens. Use the supported alternative or have the owner perform the action in the cabinet. More scopes do not open it. |
| `403 PAT_CONTOUR_MISMATCH` | The DEV key cannot access this live operation or method. Follow the passport's denied-method lists and have the owner choose the appropriate workflow. |
| Other `403` | A role, resource or operation-specific access gate may still deny access. Check that method's reference and [Troubleshooting](/docs/troubleshooting). |

A public catalogue request can answer **200 without `catalog:read`**, returning
an anonymous view: only public data, with no owner-only draft visibility.
Therefore “200 on `/products`” is not an authentication test. A successful
passport verifies the key; a successful write still requires rereading the
object and checking the storefront. No unknown scope grants extra access.

## 5. Expiry, revocation and secret handling

Never put plaintext keys in source files, HTML, browser-side JavaScript, logs,
reports, chat answers or commits. Do not embed them in URLs. Keep credentials
out of uploaded site artifacts and backups intended for sharing.

A key remains usable until its expiry or revocation, subject to its principal
and resource access gates. A `null` expiry does not make it safe to retain:
leaks do not expire themselves. After a temporary task, have the owner revoke
the key in the cabinet's API access page. Revoke and replace a suspected leaked
key immediately. The passport then rejects the old key with 401; public
catalogue requests can still succeed anonymously and are not a revocation test.

Continue with [Quickstart](/docs/quickstart), a task guide, or
[the agent entry skill](/docs/skill/vizen-start).