--- title: Удостоверяване description: Два метода за удостоверяване — API ключ (Bearer) и OAuth 2.0 с PKCE — плюс Idempotency-Key за безопасни повторения и планови лимити за v1. canonical: "https://www.tracepass.eu/bg/docs/authentication" locale: bg source: "https://www.tracepass.eu/bg/docs/authentication" --- # Удостоверяване > Два метода за удостоверяване — API ключ (Bearer) и OAuth 2.0 с PKCE — плюс Idempotency-Key за безопасни повторения и планови лимити за v1. TracePass v1 поддържа два метода за удостоверяване. **API ключ** (статичен Bearer token) е най-простият — подходящ за server-to-server и ERP интеграции. **OAuth 2.0 с PKCE** е за приложения на трети страни и AI асистенти, които действат от името на потребител със scoped, отзоваем достъп. И двата се подават като Bearer token в стандартния `Authorization`header; всяка операция за запис приема и `Idempotency-Key`за безопасни повторения. Достъпни на всеки план, включително Free. Дневен лимит на заявките има само за Free (100/ден) и Basic (200/ден); Starter и по-горе са без ограничение. ## API ключове Генерирайте ключове в **Developer → API keys** в таблото. Ключовете са обвързани с работно пространство: всеки ключ е свързан с едно работно пространство и наследява неговия план, лимити и одитна следа. Ключовете носят префикс `tp_`, последван от непрозрачен случаен суфикс — няма отделен live / test префикс и няма env-неймспейснат sandbox. Тествайте в работното си пространство Free или Basic, ако ви е нужна непродукционна среда. Подавайте ключа като Bearer token при всяка заявка: ```bash curl -sS https://app.tracepass.eu/api/v1/products \ -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" ``` **Tip —** Изтекъл ключ се отзовава с едно кликване — отворете Developer → API keys, кликнете **Revoke** и ключът започва да връща 401 в рамките на секунди. Записите в одитната следа за ключа остават, за да можете да съгласувате какво е било записано под него. ## OAuth 2.0 (приложения, авторизирани от потребител) Когато изграждате приложение, което други потребители на TracePass свързват — или AI асистент, който потребител авторизира — използвайте OAuth 2.0, вместо да искате от тях да поставят API ключ. Потребителят одобрява конкретни scopes на екран за съгласие; токенът за достъп, който генерира, е ограничен до сечението на ролята му в таблото и одобрените scopes. Регистрирайте приложението си в **Developer → OAuth Apps** (или програмно чрез Dynamic Client Registration на `/api/oauth/register`). Поддържаме **authorization-code flow с PKCE** — публичните клиенти (SPA / мобилни / MCP) не се нуждаят от secret; поверителните сървърни клиенти получават такъв. ### Потокът Discovery метаданните са на `/.well-known/oauth-authorization-server` (RFC 8414). Накратко: (1) насочете потребителя към `/api/oauth/authorize` с вашия `client_id`, `redirect_uri`, заявен `scope`, `state` и PKCE `code_challenge` (`S256`); (2) той одобрява и ние пренасочваме обратно с еднократен `code`; (3) разменете го на `/api/oauth/token` с вашия `code_verifier` за 15-минутен токен за достъп (плюс refresh token, ако е одобрен `offline_access`). Refresh токените се ротират при всяко използване; отзовавайте на `/api/oauth/revoke` (RFC 7009). ### Scopes Заявявайте само това, от което приложението ви се нуждае — екранът за съгласие показва на потребителя точно тях. Scope за запис допълнително изисква авторизиращият потребител да има роля с права за запис, така че viewer, който одобри `passports:write`, все пак не може да записва. API ключовете, за разлика от тях, са „всичко или нищо“ и пренебрегват scopes. | Scope | Дава достъп до | | --------------- | -------------------------------------------------- | | passports:read | Преглед на продукти и цифрови продуктови паспорти | | passports:write | Създаване, актуализиране и публикуване на паспорти | | documents:read | Четене на качени документи и извличания | | documents:write | Качване на документи и стартиране на AI извличания | | suppliers:read | Преглед на заявки към доставчици | | suppliers:write | Създаване и управление на заявки към доставчици | | offline\_access | Издаване на refresh token (оставате свързани) | **Tip —** Потребителите виждат и прекъсват приложенията, които са авторизирали, в **Developer → OAuth Apps → Connected Apps**; прекъсването отзовава токените на приложението незабавно. Можете да изтриете собствените си регистрирани приложения от същия екран. ## Idempotency-Key Всеки `POST`, `PATCH` и `DELETE` по v1 повърхността приема `Idempotency-Key` header. Изпратете UUID v4 (или произволен непрозрачен низ ≤ 255 знака) за всяка логическа операция; платформата съхранява първия отговор за 24 часа и го повтаря, ако същият ключ + същото работно пространство се появят отново. Повторенията по мрежата стават безопасни — няма да създадете два пъти паспорт, защото вашият HTTP клиент е направил повторение при преходен 5xx. ```bash curl -sS https://app.tracepass.eu/api/v1/passports \ -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \ -H "Idempotency-Key: 7b4f1e2c-9a3d-4e5b-8c1a-2d3e4f5a6b7c" \ -H "Content-Type: application/json" \ -d '{ "productId": "...", "gs1": { "gtin": "...", "serialNumber": "..." } }' ``` Повторно използване на същия ключ с **различно тяло на заявката** връща`422 Unprocessable Entity` с `error: "Idempotency-Key has already been used with a different request body. Use a new key for the new request, or reuse the original body."` — платформата не презаписва тихомълком, защото това почти винаги е грешка в клиента. Генерирайте нов ключ за реално нови операции. ## Лимити на честотата Прилагат се два тавана за UTC ден, за работно пространство: ### 1\. v1 бюджет за записи — \`maxV1WritesPerDay\` Брои всеки `POST` / `PATCH` / `DELETE` по v1 повърхността. Четенията не са включени в този брояч. ### 2\. v1 бюджет за четене на паспорти — \`maxV1PassportsPerDay\` Брои всеки `GET` по endpoints за паспорти (единично четене + пагиниран списък). Отделен от бюджета за запис, така че ERP, който изпраща актуализации, да не изяде квотата ви за четене и обратно. | План | Записи / ден | Четения на паспорти / ден | | ---------- | ------------ | ------------------------- | | Free | 100 | 100 | | Basic | 200 | 200 | | Starter | Неограничено | Неограничено | | Growth | Неограничено | Неограничено | | Scale | Неограничено | Неограничено | | Pro | Неограничено | Неограничено | | Enterprise | Неограничено | Неограничено | Когато достигнете единия от двата тавана, отговорът е `429 Too Many Requests` с тяло от типа `{ "error": "API rate limit: 200 writes/day via /api/v1. Currently 200 today; requested 1. Retry tomorrow (UTC) or upgrade your plan." }`. Прозорецът се нулира в 00:00 UTC; не поддържаме плъзгащи се прозорци, защото те правят лимита по-труден за разсъждение надолу по веригата. Отделна квота — `maxDpps` — ограничава общия брой активни DPP в работното ви пространство и се прилага чрез отговор `402` с тяло `overage_required`, когато планът поддържа overage за паспорт. Виж endpoint-а [Create a passport](/bg/docs/create-passport) за overage потока. **Нужен ви е по-голям лимит?** Направете upgrade на плана си в таблото (мигновено) или се свържете с [support@tracepass.eu](mailto:support@tracepass.eu) за Enterprise оферта. Не таксуваме на сканиране в публичния преглед на паспорта — броят се само записите през това API. ## Какво още не поддържаме OAuth **client-credentials** grant-ът (машинна идентичност без потребител) и IP allow-listing са в roadmap-а, но все още не са пуснати. За чист server-to-server достъп днес използвайте API ключ — генерирайте по един за всяка интеграция, за да можете да го отзовете на ниво интеграция.