API kľúče a audit logy

ProcureSwift poskytuje REST API, ktoré umožňuje externým systémom programovo čítať a zapisovať procurementové dáta. Prístup je riadený pomocou API kľúčov — dlhodobých tajných hodnôt viazaných na konkrétneho tenanta, obmedzených na vybrané zdroje a s limitom počtu požiadaviek za minútu. Každé volanie API kľúčom je zaznamenané v Auditných záznamoch API, takže administrátori môžu presne vidieť, čo ktorý kľúč vykonal.

Kde to nájdete

• API kľúče: hlavné menu → API kľúče (/api-keys).
• Auditné záznamy API: hlavné menu → Auditné záznamy API (/api-audit-logs).

Obe stránky vyžadujú oprávnenie ApiKeys / View. Vytváranie, revokovanie a mazanie kľúčov vyžadujú postupne oprávnenia ApiKeys / Create, ApiKeys / Manage a ApiKeys / Delete.

Vytvorenie API kľúča

1. Otvorte API kľúče a kliknite na Vytvoriť API kľúč.
2. Vyplňte formulár:
   • Názov — popis, ktorý identifikuje, na čo kľúč slúži (napríklad Xero sync alebo Internal data export). Povinné.
   • Rozsahy prístupu — zaškrtnite zdroje a akcie, ktoré tento kľúč smie vykonávať. Ak nezaškrtnete nič, kľúč dostane všetky scopy. Dostupné scopy:
     • purchase_orders:read, purchase_orders:write
     • invoices:read, invoices:write
     • catalog:read
     • delivery_notes:read, delivery_notes:write
     • quotations:read, quotations:write
     • proposals:read, proposals:write
     • rfqs:read, rfps:read
     • webhooks:manage
   • Platnosť do — voliteľný dátum expirácie, po ktorom kľúč prestane fungovať. Ponechajte prázdne pre kľúč bez expirácie.
   • Limit / min — maximálny počet požiadaviek za minútu. Predvolená hodnota je 100. Rozsah je 1 až 10000.
3. Kliknite na Vytvoriť.

Jednorazové zobrazenie kľúča

Bezprostredne po vytvorení sa plná hodnota API kľúča zobrazí raz v potvrdzovacom dialógu. Skopírujte ju hneď a uložte do správcu hesiel alebo trezoru tajomstiev — platforma ju už nikdy nezobrazí. Ak kľúč stratíte, revokujte ho a vytvorte nový.

Po vytvorení zoznam zobrazuje iba prefix kľúča (prvé znaky), aby bol identifikovateľný v logoch bez odhalenia celého tajomstva.

Správa existujúcich kľúčov

Tabuľka Aktívne kľúče na /api-keys zobrazuje: Názov, Predpona kľúča, Rozsahy prístupu, Platnosť do, Stav, Naposledy použité, Limit požiadaviek, Vytvorené.

Akcie pre každý riadok:

• Odvolať (ikona blokovania) — okamžite deaktivuje kľúč. Ďalšie požiadavky s týmto kľúčom budú zamietnuté. Revokované kľúče zostanú v zozname so stavom Odvolaný na účely auditu.
• Odstrániť (ikona koša) — trvalo odstráni záznam kľúča. Použite na upratanie kľúčov, ktoré sú revokované dlhšie než je doba uchovávania auditných záznamov.

Kľúč, ktorý dosiahol dátum expirácie, je automaticky neaktívny — stĺpec Platnosť do sa zobrazuje červenou farbou.

Používanie API kľúča

Kľúč odovzdajte v hlavičke Authorization pri každom API požiadavku:

Authorization: ApiKey <your-key>

Spolu s identifikátorom tenanta v hlavičke tenant to serveru stačí na autentifikáciu a určenie rozsahu požiadavky.

Auditné záznamy API

Stránka Auditné záznamy API zaznamenáva každý HTTP požiadavok vykonaný pomocou API kľúča. Každý riadok zobrazuje:

• API kľúč — názov použitého kľúča.
• Metóda HTTP — HTTP metóda (GET / POST / PUT / DELETE), farebne odlíšená.
• Cesta — endpoint, ktorý bol volaný.
• Stav — HTTP stavový kód, farebne podľa triedy (2xx zelená, 4xx oranžová, 5xx červená).
• IP adresa — IP adresa klienta, z ktorej volanie prišlo.
• Trvanie — čas trvania volania v milisekundách.
• Čas záznamu — čas, kedy k volaniu došlo.

Na filtrovanie logu podľa konkrétneho kľúča použite rozbaľovací zoznam Filtrovať podľa API kľúča.

Log je stránkovaný (predvolene 25 riadkov na stránku) a zoradený od najnovšieho záznamu.

Tipy

• Vytvorte jeden kľúč na každú integráciu, nie jeden zdieľaný kľúč pre všetko — ak dôjde ku kompromitácii jednej integrácie, jej revokovanie neovplyvní ostatné.
• Nastavte úzke scopy. Skript určený iba na export by mal dostať len scopy :read.
• Využite limit počtu požiadaviek na ochranu platformy aj externého systému. Chybný skript, ktorý bombarduje API v tesnej slučke, je oveľa ľahšie diagnostikovať, keď dostane 429 Too Many Requests, než keby stiahol závislú službu.
• Pravidelne kontrolujte audit log a hľadajte neočakávané endpointy alebo zhluky chýb 4xx/5xx — často signalizujú integráciu, ktorá potrebuje údržbu.

Oprávnenia

Akcia	Požadované oprávnenie
Zobraziť kľúče, zobraziť audit log	ApiKeys / View
Vytvoriť nový kľúč	ApiKeys / Create
Revokovať kľúč	ApiKeys / Manage
Vymazať kľúč	ApiKeys / Delete

Súvisiace príručky

• Webhooky — príjem real-time notifikácií o udalostiach z platformy.