Calven authenticates API requests with API keys. When Calven creates a key it has two distinct properties:

Permissions - the set of endpoints the key can call

Authentication type - whether the key is used for Basic authentication or for token-based (HMAC) authentication

Your API keys carry broad access to your data, so keep them secure.

To use the API you will require an API key and secret, which can be created in Calven.

Authentication

Calven supports two types of authentication:

Basic authentication

HMAC authentication

Basic authentication sends the API key and secret with each request.

HMAC authentication never transmits the secret with the request. Instead, it uses the secret to generate a hashed message authentication code (HMAC) based on the request data. The secret stays confidential and does not travel over the wire, making it less susceptible to man-in-the-middle attacks. Additionally, because the recipient can independently compute the expected HMAC using the shared secret, it helps verify both the integrity and authenticity of the request.

Each key is created for one authentication type, not both:

A standard key authenticates through the /v1/auth endpoints to obtain a bearer token, and cannot be used for Basic authentication. Use this type if your client can compute an HMAC or you use Calven's SDKs.

A Basic authentication key works only on the /basic endpoint variants, and cannot be used with the /v1/auth endpoints. Use this type if your tools cannot calculate an HMAC as part of the request.

Access Control

Each API key carries a set of permissions, chosen when the key is created. Each endpoint requires a specific permission, and a request from a key without that permission is rejected.

A key's permissions cannot be changed after creation. To change what a key can access, create a new key.

Permission	Grants	Endpoints	Returns personal data
`dm:group:hierarchyrelationship:write`	Write group hierarchy relationships	`PUT /v1/directory/group-hierarchy-relationship`	No
`dm:user:attribute:write`	Write user attributes	`POST /v1/directory/user-attributes`	No
`event:read`	Read event data	`GET /v1/analytics/events`	No
`group:read`	Read groups	`GET /v1/analytics/groups`	No
`location:occupancy:write`	Submit occupancy events	`POST /v1/occupancy`	No
`location:read`	Read locations	`GET /v1/analytics/locations`	No
`parking:booking:read`	Read parking booking reports	`GET /v1/parking/booking-report`	Yes
`user:accesscredential:write`	Create and update user access credentials	`POST /v1/access-credentials`	No
`user:booking:read`	Read booking and attendance data	`GET /v1/analytics/change-log/user` `GET /v1/analytics/user-booking-attendance`	Yes
`user:plan:write`	Submit time off updates	`POST /v1/timeoff`	No
`user:presence:read`	Read presence data	`GET /v1/analytics/presence`	Yes
`user:presence:write`	Submit presence events	`POST /v1/presence`	No
`user:profile:read`	Read user profiles	`GET /v1/analytics/users`	Yes
`visitor:arrival:write`	Submit visitor arrival events	`POST /v1/visitor-arrival`	No

GET /v1/analytics/desks requires both location:read and user:profile:read.

The /basic variants of endpoints require the same permissions as the token-authenticated endpoint.

Access Control

Authentication#

Access Control#

Authentication

Access Control