Authentication

Sending the key

Send the key in the header Authorization: Bearer maci_live_.... The key is accepted only in that header and only over HTTPS. A call without a valid key gets 401.

Authorization: Bearer maci_live_...

Making and rotating keys

The organisation's admins create, rotate and delete API keys in the app under Konto → API-nøgler. A key is shown once, when it is created. Maci Service (Premium) is bought in the app as a number of subscriptions, and each is on one unit or unassigned. The API only reaches units that have one: a unit without Maci Service is left out of lists and answers 403. The subscriptions endpoints list the organisation's subscriptions and give an unassigned one to a unit, or take one off, so an integration can decide which units have Maci Service.

Keys are made under Konto → API-nøgler. Every key expires, after 90 or 365 days as chosen when it is made. Rotating a key makes a new one with the same name and scopes; the old one keeps working for 24 hours, so your systems can change over without a gap. Deleting a key stops it at once.

Sandbox and production

There is one API, and the key decides where a call works. A production key starts with maci_live_ and works on the organisation's real units. A sandbox key starts with maci_sandbox_ and works on the organisation's own sandbox: test data that starts with a site and two units, and that nothing in production can see or be changed by. Addresses, scopes, limits, errors and answers are the same in both, so moving to production is a matter of changing the key. Every answer has the header Maci-Environment with sandbox or production. Sandbox calls do not count towards the monthly limit, and a label (tag_code) cannot be used in the sandbox.

What a key can reach

A key can never do more than the organisation itself. An owner's key reaches the organisation's own units. A service company's key reaches the units where the company has an active grant. Grants are checked on every call. Each endpoint asks for a scope, which is chosen per key.

The API gives an organisation's own systems access to the data the organisation has in Maci Service, the alarms from Maci Intelligence and, for a service company, its invoice bases. Webhooks post alarms and approved invoice bases to an address of the organisation's own.

Login, passkeys, grants, invitations, API keys and administration can only be handled in the web app.

Scopes

Each endpoint asks for one scope. Give a key only the scopes it needs. A call with a key that lacks the scope gets 403 with the code missing_scope.