Skip to content

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.

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.

uml diagram

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

Work in progress. As soon as we finish load tests we will complete this section with rate limits and mean latencies.