API keys

An API key is a bearer token for scripts, storefronts, CI jobs and agents. Every key belongs to one organization and starts with pim_. Send it as Authorization: Bearer pim_… on any /v1 request.

In the admin

API keys live under System → API keys.

1. Type a name in the Name field (for example storefront-prod) so you can recognise the key later.
2. Click Issue key.
3. The banner New key issued — copy now shows the full key. Click Copy and store it in your secret manager, then click Dismiss.
4. The key appears under Existing with its name, its first characters (pim_abcd…), Last used and Created.

To rename a key, hover the row and click the pencil, or double-click the name, then press Enter. To retire a key, click Revoke and confirm. Revoked keys stay in the list, greyed out and marked revoked, and can no longer be renamed in the admin.

The same page has an Integration prompt for LLMs panel. Click Show prompt, pick a channel, and copy a prompt that already contains your API base URL, organization id, channel code and default locale. The key itself is never included; the prompt tells the assistant to read it from MINIPIM_API_KEY.

With the API

Method	Path	What it does
GET	/v1/api-keys	List keys for the current organization
POST	/v1/api-keys	Create a key. The response includes the plaintext key
PATCH	/v1/api-keys/{id}	Rename a key (name is the only editable field)
POST	/v1/api-keys/{id}/revoke	Revoke a key
GET	/v1/me	Check which organization a key resolves to

curl -X POST https://api.minipim.com/v1/api-keys \
  -H 'Authorization: Bearer pim_…' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "nightly-export", "expiresAt": "2027-01-01T00:00:00Z" }'

expiresAt is optional and only settable over the API; the admin form issues keys that never expire. Full request and response schemas are in the API reference.

Rules and limits

• The plaintext key is returned once, at creation. minipim stores only a SHA-256 hash and cannot show the key again. If you lose it, issue a new one and revoke the old one.
• Lists show only a short prefix (pim_ plus four characters), never the key.
• A key carries its own organization. You do not need an x-organization-id header when you authenticate with a key; the server takes the organization from the key.
• A revoked or expired key returns 401 unauthenticated. Because resolved keys are cached briefly, a revoked or just-expired key can keep working for up to about 60 seconds.
• Revoking an already-revoked key returns 404.
• Expiry cannot be changed after creation. To extend a key, issue a new one.
• Last used is updated at most about once a minute per key, so treat it as approximate.
• Changes made with a key are recorded in the audit log with the actor type api_key.
• Creating, renaming and revoking keys emits api_key.created, api_key.updated and api_key.revoked.

See REST API basics for request conventions and TypeScript SDK for a client that sets the header for you.