Authentication

API key format, permissions, idempotency, and rate limits in the plugin integration API.

Every call to /api/v1/plugin/* must include a valid X-Api-Key header.

Key format

mk_live_<keyId>.<secret>

Plugin keys belong to exactly one plugin installation. The merchant creates the installation in Settings → Plugin Installations and then generates the key in Settings → API Keys; the secret half is shown only once, when the key is created.

Creating your first key

A working key requires an active plugin installation — keys without an installation are rejected by every /api/v1/plugin/* endpoint.

Create the installation. In your team settings open Settings → Plugin Installations and add an installation for your shop platform. The installation defines the maximum set of permissions any of its keys can have.
Create the key. Open Settings → API Keys, create a new key and select your installation. The installation's permissions are applied to the key automatically; you can narrow them, but not broaden them.
Copy the secret into the plugin. The full key (mk_live_<keyId>.<secret>) is shown only once, right after creation. Paste it into your plugin's Qamera AI settings. If you lose it, create a new key — the secret cannot be displayed again.

Key permissions (scope)

Every key is issued with one or more permissions. The effective set is the intersection of the key's permissions and the installation's permissions — a key can be narrower than the installation, but never broader.

Permission	Endpoints
`plugin.jobs:create`	`POST /jobs`, `POST /jobs/batch`, `POST /orders/{id}/clone`
`plugin.jobs:read`	`GET /jobs`, `GET /jobs/{id}`, `GET /orders/{id}`, `POST /jobs/{id}/refresh-url`, `POST /jobs/{id}/accept`, `POST /jobs/{id}/reject`, `GET /presets`
`plugin.jobs:cancel`	`DELETE /jobs/{id}`
`plugin.assets:upload`	`POST /assets/upload`
`plugin.catalog:read`	`GET /models`, `GET /sceneries`, `GET /ai-models`, `GET /aspect-ratios`, `GET /pricing`, `GET /presets`, `GET /products`, `GET /products/{id_or_ref}`, `GET /packshots`
`plugin.catalog:write`	`POST /images`, `POST /packshots`, `DELETE /products/{id_or_ref}`, `DELETE /packshots/{id_or_ref}`
`plugin.installations.manage`	`POST /installations/{id}/rotate-hmac`
`plugin.webhooks:manage`	`POST /webhooks/{delivery_id}/replay`

GET /me works with any valid key. Calling a route without the required permission returns 403 forbidden.

Rate limit

Each key has a per-minute request limit (default 60). Once it is used up, the next call returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 47
Content-Type: application/json

{ "error": { "code": "rate_limit_exceeded", "retryable": true, ... } }

Retry the call after Retry-After seconds.

Idempotency

Write operations accept the Idempotency-Key: <token> header. For 24 hours, resending the same request with the same token returns the previous result instead of creating a duplicate; after that window the token is treated as new. The same token with a different body returns 409 idempotency_conflict.

Recommendation: derive the token from a local operation identifier in your shop (e.g. zamowienie-12345-wysylka).

Access

The Plugin API is available to all accounts — no sign-up or enrollment is needed beyond creating an installation and a key. If access is disabled for your account, every call returns 503 with Retry-After: 3600; in that case contact support@qamera.ai.

Errors

All errors share a common format — see the error reference for the full list of codes.