Authentication

Vizito accepts three credentials on the same API, side by side. Which one you use is entirely your choice.

Method	Header	Secret lives
API key (recommended)	`Authorization: Bearer vzk_...`	With Vizito, hashed
Microsoft Entra ID	`Authorization: Bearer <access token>`	In your own directory
Username and password	`Authorization: Basic ...`	With Vizito

Basic authentication with a Backoffice login still works and existing integrations keep running. It is no longer the recommended way: it hands out a person’s password, it cannot be rotated without locking that person out, and it dies with their account. Use an API key instead.

Creating an API key

Open the Integrations page as a global admin

backoffice.vizito.be → Integrations. Only global admins can manage keys — a key can span several locations and outlives whoever created it, so issuing one is an account-wide decision.

Fill in the form

Name — say which integration it is for. It is what you will read on the “last used” list a year from now.
Locations — tick every location this integration needs. It gets nothing outside them.
Expiry — never, 30 days, 90 days or a year.
IP addresses (optional) — single addresses or CIDR ranges the key may be used from.

Copy the key

It is shown once. Vizito stores only a SHA-256 hash and cannot show it again — lose it and you create a new one.

Manage your API keys

Create, revoke and delete keys on the Backoffice Integrations page.

Using the key

A key looks like vzk_<key id>_<secret>. Send it as a bearer token:

curl https://api.vizito.eu/api/companiesList \
  -H "Authorization: Bearer vzk_1a2b3c4d5e6f7890_..."

const response = await fetch('https://api.vizito.eu/api/companiesList', {
  headers: { Authorization: `Bearer ${process.env.VIZITO_API_KEY}` }
});
const locations = await response.json();

import os, requests

response = requests.get(
    "https://api.vizito.eu/api/companiesList",
    headers={"Authorization": f"Bearer {os.environ['VIZITO_API_KEY']}"},
)
locations = response.json()

$ch = curl_init('https://api.vizito.eu/api/companiesList');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . getenv('VIZITO_API_KEY')]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$locations = json_decode(curl_exec($ch), true);

If a bearer token is awkward in your tooling, the same value is accepted in an X-API-Key header.

What a key may do

A key is its own principal, not a stand-in for the admin who created it. On the locations it was granted it has full administrator access; outside them it has none at all. It keeps working when that admin is demoted, moved or leaves — an integration should not break because somebody changed jobs. There are three things a key deliberately cannot do, so that a leaked key cannot escalate into an account:

Create locations

It works inside the locations it was given; it does not hand out new ones.

Manage users

No creating Backoffice logins, changing roles or resetting passwords.

Manage API keys

No minting replacements, so revoking one actually means something.

Those endpoints answer 403 for a key, whatever it covers. Do them in the Backoffice.

Every restriction is checked per request

Revoking a key, letting it expire, narrowing its locations or changing its IP list takes effect on the very next call. There is no cache to wait out.

Every refusal answers the same way: 403 with {"error": "Invalid API key"} — whether the key is unknown, revoked, expired, used from the wrong IP address or aimed at a location it does not cover. That is deliberate: a more specific message would tell whoever holds a stolen key exactly what to try next. The real reason is in the Vizito server log; if you are stuck, support can read it back to you.

When debugging a 403, work down this list:

Is the header exactly Authorization: Bearer <key>, one space, nothing truncated?
Is the key still active and not past its expiry date? Both are visible in the Backoffice.
Is the calling server’s IP address in the key’s whitelist — including the new one you deployed to last week?
Does the key cover the location you are addressing? Check against GET /companiesList.

Thirty refused attempts from one IP address in fifteen minutes gets you 429 for the rest of the window. Successful requests never count towards it.

Microsoft Entra ID

If you would rather not store a Vizito secret at all, register your application in your own Entra ID directory and let Vizito trust tokens it issues.

Add a client secret or a certificate, and note the Directory (tenant) ID and the Application (client) ID.

On the Integrations page, create a credential with authentication type Microsoft Entra ID and enter both ids. Pick its locations exactly as you would for an API key.

Get a token

POST https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<client id>
&client_secret=<client secret>
&scope=<client id>/.default

Call the API with it

Authorization: Bearer <access token>. Tokens are valid for about an hour; ask for a fresh one when it expires.

Vizito verifies the signature against Microsoft’s published keys, that the token comes from the registered tenant, that its audience is the registered application, and that it was issued through the client credentials grant rather than delegated from a user. From there on it behaves exactly like an API key: same locations, same permissions, same restrictions.

Keeping keys healthy

One key per integration

Sharing a key across two systems means revoking it breaks both, and “last used” tells you nothing. Keys are free — make one each.

Give it only the locations it needs

A key for a badge printer at one site has no business reading the visitor log of another.

Restrict by IP where you can

A server integration calls from a known address. Whitelisting it makes a leaked key useless anywhere else — just remember to update the list when you move servers.

Check 'last used' before revoking

The Integrations page shows when each key was last seen. It is the quickest way to tell a live integration from a forgotten experiment.

Getting started

Locations

Visitors

Registered visitors

Hosts

Visit types

Entry points

Agreements

Devices

Reporting

Webhooks

Authentication

Creating an API key

Manage your API keys

Using the key

What a key may do

Create locations

Manage users

Manage API keys

Every restriction is checked per request

Microsoft Entra ID

Keeping keys healthy

​Creating an API key

Manage your API keys

​Using the key

​What a key may do

Create locations

Manage users

Manage API keys

​Every restriction is checked per request

​Microsoft Entra ID

​Keeping keys healthy

Creating an API key

Using the key

What a key may do

Every restriction is checked per request

Microsoft Entra ID

Keeping keys healthy