Authentication

1. What the key is

The key is a string you receive from us, tied to one taxpayer and to your software. It is not created from a screen and it is not generated from a profile.

Every key carries one or more scopes. The Integration API needs the IntegrationApi scope — that is what allows the key to call the addresses under api/integration/v1. A key without it is a valid key, but every call to the Integration API is rejected with EARH-1005 and status 403.

2. Two required headers

Every request to the Integration API carries both of the headers below. Neither is optional and neither can be replaced by anything else.

Header	What it carries	When it is missing
`X-Api-Key`	the key you were issued	`EARH-1001` · `401`
`X-Software-Id`	an identifier of the calling software — name and version, free text, e.g. `AccountingPro/2.4`	`EARH-1008` · `400`

X-Software-Id does not affect what the key is allowed to do. It is there so we can recognise your software in the logs when you come to us with a question.

3. A working example

GET /api/integration/v1/ping does not touch a single document — it only says whether the key was accepted. Copy the whole command and replace the two placeholders — the key and your software’s identifier:

curl -i -X GET "https://sandbox.api.earhiva.mk/api/integration/v1/ping" \
  -H "X-Api-Key: <YOUR KEY>" \
  -H "X-Software-Id: <NAME AND VERSION OF YOUR APPLICATION>"

On success it returns 200 and a body:

{
  "ok": true,
  "keyValid": true,
  "serverTime": "2026-08-25T10:14:03.412+02:00"
}

keyValid: true means the key was accepted, that it is valid, and that it carries the IntegrationApi scope. From here on every call goes with the same two headers.

4. What else can go wrong

Apart from missing headers and a missing scope, the key can be rejected in these three cases as well:

Code	HTTP	What it means
`EARH-1002`	`401`	the key has passed its expiry date and has to be renewed
`EARH-1003`	`401`	the key has been revoked and no longer works
`EARH-1004`	`403`	the request comes from an address that is not on the allowed list for that key

Every code in the error catalogue also carries exactly what to do about it.