Avtentikacija in ključi

Vsaka zahteva (razen /v1/meta/status, /v1/reference/* in /v1/openapi.json) potrebuje API ključ.

Vrste ključev

Predpona	Vrsta	Uporaba
mk_	skrivni	samo na strežniku; pravi podatki; obračunan po enotah
mk_pub_	javni (publishable)	v brskalniku; samo /v1/autocomplete in /v1/vat/validate; seznam dovoljenih izvorov; lastna majhna kvota; od paketa Starter

Skrivni ključ je en sam, brez ločenega testnega in produkcijskega okolja. Starejši ključi s predpono mk_live_ delujejo še naprej. Testni ključi mk_test_ so ukinjeni in vrnejo 401 test_keys_removed.

Število skrivnih ključev je odvisno od paketa: Hobi 1, Starter 3, Growth 10, Custom neomejeno. Javne ključe mk_pub_ lahko ustvarite od paketa Starter naprej; na paketu Hobi vrnejo 403 plan_upgrade_required.

Za preizkušanje zahtev uporabite preizkuševalnik API-ja v nadzorni plošči: dela na pravih podatkih, ne porablja enot in ni obračunan, omejen pa je na približno 20 zahtev na minuto.

Ključ je sestavljen iz predpone, 43 znakov base62 in 6-mestne kontrolne vsote CRC32, zato tipkarske napake zavrnemo brez poizvedbe v bazo. Pri nas je shranjen samo HMAC ključa; ključa ne moremo prikazati ponovno.

Pošiljanje ključa

GET /v1/entities/80267432 HTTP/1.1
Host: api.maticna.si
Authorization: Bearer mk_…

Alternativa je glava X-API-Key: mk_….

Nikoli v URL-ju

Ključ v query stringu (?api_key=…) vrne 400 key_in_query_forbidden in ključ samodejno prekličemo, ker je URL že v dnevnikih proxyjev, CDN-jev in brskalnika. Glej key_in_query_forbidden.

Zakaj skrivni ključi ne sodijo v brskalnik

Vse, kar pošljete v brskalnik, lahko vsak prebere v orodjih za razvijalce. Skrivni ključ v JavaScriptu na spletni strani pomeni, da lahko kdorkoli porablja vašo kvoto in dostopa do vseh končnih točk. Kličite API s svojega strežnika ali uporabite javni ključ.

Javni ključi in CORS

• Skrivni ključi ne dobijo glav CORS; brskalnik takšen odgovor zavrne.
• Javni ključi vrnejo Access-Control-Allow-Origin samo za izvore na seznamu dovoljenih. Drugi izvori dobijo 403 origin_not_allowed.
• Glava Origin je izven brskalnika lahko ponarejena. Javni ključ je zato odvračilo, ne varnost: ima ločeno majhno kvoto in le dve končni točki.

// v brskalniku, z javnim ključem
const r = await fetch(`https://api.maticna.si/v1/autocomplete?q=${encodeURIComponent(q)}`, {
  headers: { Authorization: 'Bearer mk_pub_…' },
});

Obsegi (scopes)

Obseg	Končne točke
entities:read	iskanje po ID-jih, paketno iskanje, preverjanje DDV in davčne
entities:search	GET /v1/entities
autocomplete	GET /v1/autocomplete
changes	/v1/changes, zgodovina subjekta
monitors	/v1/monitors (opazovani subjekti)
webhooks	/v1/webhook-endpoints

Nov skrivni ključ ima privzeto obsege entities:read, entities:search, autocomplete in monitors; ostale (changes, webhooks) izberete ob ustvarjanju, če jih vaš paket vključuje. Ključi, ustvarjeni pred 21. 10. 2026, obdržijo svoje obsege (monitors jim po potrebi dodate z novim ključem). Paket Hobi nima mest za opazovane subjekte, zato dodajanje vrne 403 plan_upgrade_required tudi z obsegom monitors.

Manjkajoč obseg vrne 403 insufficient_scope.

Rotacija in preklic

V nadzorni plošči ključ rotirate z odlogom 0–7 dni (stari in novi ključ v tem času delujeta oba) ali ga takoj prekličete. Ustvarjanje in rotacija zahtevata ponovno potrditev identitete. Opcijsko lahko ključ omejite na seznam IP naslovov.