Uwierzytelnianie

Format klucza API, scope, idempotencja i ograniczenie szybkości w API integracji wtyczek.

Każde zapytanie do /api/v1/plugin/* musi zawierać prawidłowy nagłówek X-Api-Key.

Format klucza

mk_live_<keyId>.<secret>

Klucze pluginowe są powiązane z dokładnie jednym wpisem plugin_installations. Sprzedawca generuje je w Ustawienia → Plugin Installations; sekretna część jest pokazana raz przy tworzeniu i nigdy więcej.

Scope

Każdy klucz jest wystawiony z jednym lub więcej scope. Efektywny zestaw to przecięcie scope klucza i scope instalacji — klucze mogą być węższe niż instalacja, ale nigdy szersze.

Scope	Endpointy
`plugin.jobs:create`	`POST /jobs`, `POST /jobs/batch`
`plugin.jobs:read`	`GET /jobs`, `GET /jobs/{id}`, `POST /jobs/{id}/refresh-url`, `GET /presets`
`plugin.jobs:cancel`	`DELETE /jobs/{id}`
`plugin.assets:upload`	`POST /assets/upload`
`plugin.installations.manage`	`POST /installations/{id}/rotate-hmac`
`plugin.webhooks:manage`	`POST /webhooks/{delivery_id}/replay`

GET /me jest dostępne z dowolnym ważnym kluczem. Wywołania trasy bez wymaganego scope zwracają 403 forbidden.

Ograniczenie szybkości

Każdy klucz ma rate_limit_per_min (domyślnie 60). Gdy bucket jest wyczerpany, następne zapytanie zwraca:

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

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

Powtórz po Retry-After sekundach.

Idempotencja

Mutacje akceptują Idempotency-Key: <token>. Serwer przechowuje (installation_id, key, sha256(canonical_payload)) i odtwarza poprzedni wynik przez 24h; po tym oknie token jest traktowany jako nowy. Ponowne użycie klucza z innym payloadem zwraca 409 idempotency_conflict.

Zalecane: wyprowadź klucz z lokalnego ID zamówienia (np. order_12345-submit).

Beta gate

Dostęp do API integracji wtyczek jest bramkowany per-konto podczas stabilizacji powierzchni. Konta jeszcze nie na liście beta widzą 503 z Retry-After: 3600 na każde wywołanie. Skontaktuj się z support@qamera.ai aby poprosić o dostęp.

Błędy

Wszystkie błędy mają wspólną kopertę — zobacz listę błędów dla pełnej listy kodów.