API access and API keys

The Vizito API lets your own systems read and write visitor data: sign visitors in and out, keep registered visitors in sync with another database, pull reporting figures. This article covers how a system authenticates against it. The endpoints themselves are documented in the Vizito API reference.

Which authentication methods are supported?

There are three, and they can be used side by side:

Method What the caller sends Where the secret lives
API key Authorization: Bearer vzk_... Vizito (hashed)
Microsoft Entra ID Authorization: Bearer <access token> Your Entra ID directory
Username and password HTTP Basic Vizito (the user’s Backoffice password)

Basic authentication with a Backoffice login still works and existing integrations keep running, but it is no longer the recommended way: it hands your integration the same secret that opens the Backoffice, it cannot be rotated without locking the person out, and there is no record of whether it is still being used. Prefer an API key, or Entra ID if your IT policy requires the identity to live in your own directory.

What is an API key?

An API key is a separate credential meant for one integration. It can be revoked, given an expiry date and restricted to fixed IP addresses, without ever sharing a Backoffice password. Only global administrators can manage API keys.

An API key always has full access to the locations it covers, and no access at all outside them. It is not tied to the account that created it and keeps working when that account changes or is removed, so an integration does not break because a colleague left the company.

How do I create an API key?

Step 1: Open the Integrations page

Log in to the Vizito Backoffice Integrations page and scroll to “API keys”. You need to be a global administrator to see this section.

Step 2: Create the key

Click “Create API key” and fill in:

  • Name: what the key is for, for example “Access control system”. This is what you will recognise it by in the list later.
  • Authentication: “Vizito API key”.
  • Locations: the location you are on is always included; tick any other location the key should be able to reach. Only locations you have access to yourself are listed.
  • Expires: never, or after 30 days, 90 days or a year.
  • Allowed IP addresses: one IP address or CIDR range per line. Leave this empty to allow the key to be used from anywhere.

Step 3: Copy the key

The key is shown once, at creation, and cannot be retrieved afterwards. Copy it straight into the system that will use it. If you lose it, delete the key and create a new one.

Step 4: Send it with every request

Put the key in an Authorization header:

curl https://api.vizito.be/api/visitors/bycompany/<company id> \
  -H "Authorization: Bearer vzk_1a2b3c4d5e6f7890_..."

X-API-Key: vzk_... works as well, for clients that cannot set an Authorization header.

Can we authenticate with Microsoft Entra ID instead?

Yes. Vizito accepts an OAuth 2.0 access token issued by your own Entra ID tenant, so no Vizito secret has to be stored anywhere in your infrastructure. Your application authenticates against Entra ID with the client credentials grant, using either a client secret or a certificate, and sends the resulting token to Vizito. Which of the two you use is entirely between your application and Microsoft: Vizito never sees that credential.

Nothing has to be registered on the Vizito side in Entra ID, and no cross-tenant admin consent is needed. The application registration lives in your directory and stays under your control.

Step 1: Create the app registration

In the Azure portal, go to “Microsoft Entra ID” > “App registrations” > “New registration”. Give it a name, choose “Accounts in this organizational directory only” and register it. You do not need a redirect URI and you do not need any API permissions.

Under “Certificates & secrets”, add either a client secret or a certificate, whichever your policy prescribes.

From the “Overview” page, note down:

  • the Directory (tenant) ID
  • the Application (client) ID

Step 2: Register the application in Vizito

In the Backoffice, on the Integrations page, click “Create API key” and set “Authentication” to “Microsoft Entra ID”. Paste the two IDs, then pick the locations, expiry and IP restrictions exactly as you would for an ordinary API key.

Leave “Audience” empty unless you have published an application ID URI and want tokens bound to it. Empty means Vizito expects tokens issued for the application itself, which is what the request in the next step produces.

Step 3: Request a token and call the API

curl -X POST https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/token \
  -d "grant_type=client_credentials" \
  -d "client_id=<client id>" \
  -d "client_secret=<client secret>" \
  -d "scope=<client id>/.default"

Entra ID answers with an access_token that is valid for about an hour. Send it as a bearer token:

curl https://api.vizito.be/api/visitors/bycompany/<company id> \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs..."

Cache the token until it is close to expiry and request a new one after that. There is no need to fetch a fresh token per call.

What does Vizito check about the token?

On every request:

  • the signature, against the public signing keys published by your tenant
  • that the token was issued by the tenant registered on the credential
  • that it was issued to the application registered on the credential
  • that it is an application token from the client credentials grant, and not a token issued on behalf of a signed-in user
  • that it has not expired, and that the audience matches

If any of these fail the request is refused with a 401. The same applies when the credential has been revoked, has expired, or is used from an IP address outside its whitelist, so an Entra credential can be switched off from the Backoffice just as fast as an API key.

What can a credential do?

An API key or Entra credential is a global administrator on the locations it was given, and has no access whatsoever to any other location. Every request that names a location is checked against that list.

It cannot manage users or API keys. A leaked credential therefore cannot create Backoffice logins, reset anyone’s password, or issue replacement credentials for itself, which is what makes revoking it effective.

How do I revoke or delete a credential?

On the Integrations page, use the ban icon to revoke a credential and the cross to delete it. Revoking keeps the row and its history but stops it working immediately: the next request re-reads its status, so there is no delay and nothing to wait out. Deleting removes it entirely.

Any integration still using that credential stops working at once, so make sure you know what it is used for. The “Last used” column shows when the credential last made a request.

Troubleshooting

  • 401 on every request: check that the header is Authorization: Bearer <key> with a space after “Bearer”. For Entra ID, check that the tenant and application IDs in the Backoffice match the app registration exactly.
  • “This Entra ID application is not registered as an API credential”: the token is valid, but the application it was issued to is not registered in the Backoffice, or is registered on another Vizito account.
  • “Only application tokens are accepted”: the token was issued on behalf of a user rather than by the client credentials grant. Check that the request uses grant_type=client_credentials and scope=<client id>/.default.
  • 403 “not valid for that location”: the credential does not cover the location in the request. Edit it and tick that location.
  • 403 from a new server: the credential has an IP whitelist and the new server is not in it.
  • The key stopped working after a while: check the “Expires” column. An expired credential is refused until a new one is created.