Authentication and keys

Every request (except /v1/meta/status, /v1/reference/* and /v1/openapi.json) needs an API key.

Key types

Prefix	Type	Use
mk_	secret	server side only; real data; billed in units
mk_pub_	publishable	in the browser; only /v1/autocomplete and /v1/vat/validate; allowed-origins list; its own small quota; Starter plan and up

There is one kind of secret key, with no separate test and production environments. Older keys with the mk_live_ prefix keep working. Test keys (mk_test_) were discontinued and return 401 test_keys_removed.

The number of secret keys depends on the plan: Hobby 1, Starter 3, Growth 10, Custom unlimited. Publishable mk_pub_ keys are available from the Starter plan; on Hobby they get 403 plan_upgrade_required.

To try requests, use the API tester in the dashboard: it runs on real data, uses no units and is never billed, and it is limited to about 20 requests per minute.

A key consists of the prefix, 43 base62 characters and a 6-character CRC32 checksum, so typos are rejected without a database query. We store only an HMAC of the key and cannot show it again.

Sending the key

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

The X-API-Key: mk_… header works as an alternative.

Never in a URL

A key in the query string (?api_key=…) returns 400 key_in_query_forbidden and the key is revoked automatically, because the URL has already reached proxy, CDN and browser logs. See key_in_query_forbidden.

Why secret keys do not belong in the browser

Anything you send to the browser can be read by anyone in the developer tools. A secret key in a web page’s JavaScript means anyone can spend your quota and reach every endpoint. Call the API from your server, or use a publishable key.

Publishable keys and CORS

• Secret keys get no CORS headers, so the browser rejects the response.
• Publishable keys return Access-Control-Allow-Origin only for origins on the allowed list. Other origins get 403 origin_not_allowed.
• Outside a browser the Origin header can be forged. A publishable key is therefore a deterrent, not security: it has a separate small quota and only two endpoints.

// in the browser, with a publishable key
const r = await fetch(`https://api.maticna.si/v1/autocomplete?q=${encodeURIComponent(q)}`, {
  headers: { Authorization: 'Bearer mk_pub_…' },
});

Scopes

Scope	Endpoints
entities:read	lookups by ID, bulk lookup, VAT and tax-number validation
entities:search	GET /v1/entities
autocomplete	GET /v1/autocomplete
changes	/v1/changes, taxpayer history
monitors	/v1/monitors
webhooks	/v1/webhook-endpoints

A new secret key gets the entities:read, entities:search, autocomplete and monitors scopes by default; pick the others (changes, webhooks) when you create it, if your plan includes them. Keys created before 21 October 2026 keep their scopes (create a new key to get monitors). The Hobby plan has no monitor slots, so adding a monitor returns 403 plan_upgrade_required even with the monitors scope.

A missing scope returns 403 insufficient_scope.

Rotation and revocation

In the dashboard you rotate a key with a grace period of 0–7 days (the old and the new key both work during it) or revoke it immediately. Creating and rotating keys requires re-authentication. Optionally, you can restrict a key to a list of IP addresses.