Getting a token

Agents authenticate with a bearer mzk_ token on api.mozaik-dev.com — the same header for HTTP, the CLI and the MCP endpoint. Full kind/scope tables: Tokens.

The owner mints it

Tokens are minted by the store owner in the admin panel — Ajanlar ve geliştiriciler — or via tokens.mint from an owner session. There is no self-service signup for agents: the owner chooses the kind, the scopes and the expiry, and the mzk_ plaintext is shown exactly once. If you are an agent asking a human for access, ask for an Ajan token; ask for orders:read/orders:write only if the task actually touches orders (they are sensitive and off by default).

For design work the usual entry point is creating a workspace (workspaces.create) with kind agent — it mints the bound Ajan token in the same step ("workspace first, token second").

What an Ajan token can never hold

The mint dialog will not produce, and the platform will not honour, an agent token with:

• admin, agents:admin, proposals:approve, checkout — session-only, never on any token;
• secrets:write — secrets are owner-entered (a Geliştirici token may hold it only by explicit opt-in);
• design:publish — publishing is owner-side; an agent's publish intent becomes a proposal design item.

So an Ajan token structurally cannot approve its own work, set credentials, publish a design, or mint further tokens — not "is asked not to"; the scope registry refuses the grant.

First call: whoami

GET /v1/tokens/me

tokens.whoami answers with the store, kind (agent | developer), scopes, expiry and — for Ajan tokens — the bound workspace id. Call it before anything else: it tells you which store you are in (the token IS the store selector; there is no store argument anywhere) and which behaviour to expect from mutations (202-recorded vs executed). CLI: whoami.

Expiry and rotation posture

• Default expiry is tokenDefaultExpiryDays days; the owner can pick shorter at mint. Expect expiry — handle a 401 by asking the owner for a fresh token, not by retrying.
• There is no rotation endpoint yet (token.update is deferred): rotation = the owner mints a new token and revokes the old one. token.revoke is immediate and withdraws the token's open proposal.
• Per-token throttle (default tokenRateLimitPerMinDefault/min) answers 429 with Retry-After — honour it.
• Store the token in ~/.config/mozaik/credentials.json (what login does) or the MOZAIK_API_TOKEN env var. Never write it into a project tree — mozaik.json, .mozaik/ and .mcp.json are token-free by design, and the hygiene checks treat an embedded credential as a defect.