Autentifikácia

Monivio API používa Bearer token autentifikáciu. Každú požiadavku označíš API kľúčom v Authorization hlavičke. Kľúče vytvoríš v aplikácii v Nastavenia → API kľúče.

Formát kľúča

API kľúč je 35-znakový string začínajúci prefixom mk_ (Monivio Key) nasledovaným 32 base64url znakmi:

mk_2Hf8Pq3RxN4mLkZyT9aBwVvE6sCrXjQy

Hlavička požiadavky

Authorization: Bearer mk_2Hf8Pq3RxN4mLkZyT9aBwVvE6sCrXjQy

Príklad: overenie kľúča

Overenie kľúča urobíš zavolaním ľubovoľného authenticated endpointu – napríklad /contacts:

curl "https://monivio.sk/api/v1/contacts?limit=1" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Typy kľúčov

Pri vytváraní kľúča volíš jeden z dvoch typov:

• • read_only – kľúč sa vytvorí so scope-mi, ktoré obsahujú len :read akciu (žiadne :write). Akýkoľvek POST/PATCH/DELETE preto neprejde scope kontrolou a vráti 403 INSUFFICIENT_SCOPE. Vhodné pre reportovacie integrácie a dashboards.
• • read_write – plný prístup. Konkrétne povolené operácie ďalej riadia scope-y (pozri nižšie).

Scopes

Každý kľúč má povolené operácie definované formátom {resource}:{action}. Napríklad kľúč ktorý môže čítať kontakty a vytvárať dokumenty:

{
  "contacts": ["read"],
  "documents": ["read", "write"]
}

Pri každom requeste handler skontroluje scope vyžadovaný daným endpointom. Keď chýba, dostaneš 403:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Insufficient permissions: documents:write"
  }
}

Kompletný zoznam scope-ov nájdeš v Reference → Scope-y.

Bezpečnosť kľúča

• • Plaintext kľúč uvidíš len raz – pri vytvorení. Po opustení dialógu sa už neobnoví.
• • Skladujte v secret store (env premenné, AWS SSM, Vault). Nikdy v gite, frontende ani mobilnej apke.
• • Rotácia: vytvorte nový kľúč, prepnite klienta, potom starý revoke-nite. Revoke je synchrónny – ďalší request po revoku dostane 401 API_KEY_REVOKED.
• • last_used_at + last_used_ip sa logujú pri každom úspešnom request – v UI vidíš kedy a odkiaľ sa kľúč naposledy použil. Pomáha to detekovať leaky.
• • Expirácia: pri vytvorení môžeš nastaviť expiration date. Po expirácii dostaneš 401 API_KEY_EXPIRED.

Chyby autentifikácie

Auth handler vracia HTTP 401 s konkrétnym error.code podľa toho, kde request padol:

• • UNAUTHORIZED – chýba alebo má nesprávny tvar Authorization hlavička
• • INVALID_API_KEY – kľúč nemá správny formát alebo neexistuje
• • API_KEY_REVOKED – kľúč bol manuálne odvolaný v UI
• • API_KEY_EXPIRED – kľúč prekročil svoj expires_at