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 asecret
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.
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.