Usage and considerations

The API described in API Definition has the following attributes:

• It is a RESTful API using application/json.
• API authentication uses OAuth 2.0 Client Credentials Flow. You will need a client_id and a secret to obtain JWT tokens.
• The API provides user enrollment for biometric credentials issuing.
• The API provides event and attendee management.
• The creation of facilities and spaces is not exposed to the public API and must be requested to Veridas. The reason is that facilities and spaces are tightly coupled to the provision of physical access points.

• Changes to API versions will be always retrocompatible.

  * new parameters will be optional.

  * we will handle new workflows and features with different techniques like schemas or headers, without breaking current API behavior.

  * new functionality and relevant changes will be added to the section What's New.

Event lifecycle considerations

When an event is created and attendees are added through the API (POST /events and POST /attendees), the system automatically generates a temporary collection to store the biometric credentials of those attendees.

Each event has its own collection, which remains active until the corresponding event is deleted using the endpoint DELETE /events/{event_id}.

To maintain your environment organized and ensure optimal performance, it is strongly recommended to delete past events that are no longer needed.
Deleting an event automatically removes its associated collection and any stored data.

System Overview

The following diagram of the system may be useful to better understand how the API fits in the overal system.

• Users enroll through the API, and credentials are issued and stored in Cloud Database.
• Only a subset of those credentials is replicated to Edge databases, for example, when an event is created and some users are added as attendees.
• Access Points can authenticate users if they belong to that subset, and emit the acs_id to the customer's acs.

Error Handling

Ensure you correctly handle error responses like:

• invalid tokens and authentication errors
• missing required fields or bad format (HTTP 422)
• errors caused by system rules (HTTP 400, 409, etc)

HTTP 400 errors always return a dictionary with

• reason: a snake_case code.
• message: a human readable general description of the reason.

{
  "reason": "event_start_time_already_passed",
  "message": "Event creation failed"
}

Rate Limits

To ensure fair usage and system stability, the following global rate limits are enforced across all clients:

Endpoint	Method	Rate Limit	Notes
/singles (user enrollment)	POST	1 RPS	Shared across all clients
/attendees (add attendees)	POST	50 RPS	Shared across all clients

These rate limits are global, meaning they apply collectively across all users and API clients.

We recommend implementing retry logic with exponential backoff on the client side to handle rate-limiting errors gracefully.

We are continuously monitoring system performance and may adjust these limits in the future based on usage patterns and capacity improvements.