API tokens and connected apps
The two ways something other than a person reaches a store, what each can do, how to create and manage an API token, and how its limits work.
On this page
A script or an AI tool reaches a store in one of two ways: with an API token, or as an app or agent a person approved. The choice decides whether a delete or a refund runs at once or waits for a person.
| API token | Connected app or agent | |
|---|---|---|
| Examples | A script, an ERP sync, CI, poltura in a pipeline | Claude, ChatGPT, Cursor, VS Code, Codex; Poltura's own assistant |
| Created by | A person, in Poltura ID or with poltura token | A person approving a sign-in on the consent page |
| Secret | A pltu_, plto_ or pltd_ token, shown once | None you handle; the client keeps a refreshing OAuth session |
| Writes | Directly through the store's admin API and through actions on /mcp | Only through actions: run_action, run_destructive_action and the typed action tools |
| Deletes and refunds | Run at once on the admin API | Always wait for a person to approve them |
| Bounded by | Its permissions, stores, expiry, IP filter and points budget | The same, plus approval, the per-store switch and the daily caps |
A poltura login sign-in belongs on the token side: the CLI is Poltura's own client and acts as the person who
signed in, like a token. See the CLI.
Give a token only the permissions its job needs, and use an OAuth connection when a person should approve deletes and refunds. How approval works is on How agents act on your store.
Kinds of token
| Prefix | Owner | Use |
|---|---|---|
pltu_ | You | Your own scripts. Acts as you: it never holds more than your role holds. A personal token reaches one organization. |
plto_ | An organization | Server-to-server integrations that should outlive any one person. Created by someone with access.tokens.manage. |
pltd_ | A developer organization | Publishing app releases from CI. See the CLI. |
A token is 51 characters; do not assume a fixed length, since the documented maximum is 255. Its last six characters are a checksum, so a mistyped or truncated token is recognised without a network call.
Create a token
Open Poltura ID, Account, API tokens for a personal token, or the admin, Settings, Organization, API and access, for an organization token.
Choose its name, permissions, stores, IP filter and expiry (see the table below).
Copy the secret. It is shown once.
Or create it on the command line:
poltura token create --name ERP --permissions orders.read,products.write --stores all --expires 90d| Choice | Meaning |
|---|---|
| Name | What the token is for. |
| Permissions | Store permissions, such as orders.read, and organization permissions with --org-permissions. |
| Stores | all (including stores added later, with --exclude <store id> to leave some out) or a list of store ids. |
| IP filter | Allowed addresses or CIDR ranges, or none. A call from anywhere else answers ip_not_allowed. |
| Expiry | 7d, 30d (the default), 90d, 1y, a date, or never, which prints a warning. |
The secret is printed once, alone on standard output, so TOKEN=$(poltura token create …) works. Creating a token,
widening it, enabling it again and rolling it need a fresh second factor; the CLI asks for your authenticator code
or takes --otp <code>. Managing tokens takes your Poltura ID session (--access-token and --id-token, or
POLTURA_ACCESS_TOKEN and POLTURA_ID_TOKEN), never another token, so a token can never mint tokens.
Some permissions can never be given to a token or an app: managing the team, access itself, buying plans or domains, paying
invoices, and anything that needs a second factor to use. Asking for one answers not_delegable; do it in the admin.
Use a token
curl https://api.poltura.com/v1/tokens/verify -H "Authorization: Bearer $POLTURA_TOKEN"verify answers the token's id, status, expiry, owner and stores, and the IP filter does not apply to it. The same
check is poltura token verify. Send the token as Authorization: Bearer … to:
- the store's admin API,
https://api.poltura.com/v1/stores/<store id>/admin/…, where each route needs the permission the token holds for it; https://api.poltura.com/mcp, as described in Add the MCP server and Connect an AI tool.
A token limited to one store needs no store id on /mcp; a token for several takes store_id.
Change, roll and revoke
| Command | Does |
|---|---|
poltura token list | Lists tokens and when each was last used. |
poltura token edit <id> | Changes the name, policy, IP filter or expiry. The secret stays. |
poltura token roll <id> --grace 2 | Issues a new secret. The old one keeps working for the grace period, 0 to 24 hours. After a leak, roll with no grace: every old secret stops at once. |
poltura token disable <id>, enable <id> | Stops a token until it is enabled again. |
poltura token delete <id> | Revokes it for good. |
A token reported as exposed is refused immediately and its owner is emailed. The owner is also emailed seven days before a token expires, unless it was made to last a week or less. A personal token stops working when its owner leaves the organization; an organization token does not.
Limits
Every call through a token costs points from a budget that refills steadily, set by the store's plan, and an
/mcp connection also has a session budget and daily caps for money, deletes and customer messages. The tables are on
How agents act on your store. Two things differ for tokens:
- The daily caps count only actions that connected agents run. A token's direct calls to the admin API are bounded by its points budget, not by the caps.
- Every response says what the call cost and what is left in the
X-Poltura-RateLimit-*headers. A call over budget answers429 rate_limitedwithRetry-After, and a request that would cost more than 100 points answers400 request_too_costly. Neither reached the store, so a retry after the wait is safe. Both are explained in Access errors.