Calven
Calven
  • Overview
  • Key Access Levels
  • Basic Authentication Overview
  • HMAC Authentication Overview
  • SDKs
  • Calven Data Models
  • HMAC Authentication
    • Generate a token with an API key and HMAC
      POST
    • Generate a token with an API key and client secret
      POST
  • Presence
    • Presence Overview
    • Submit presence events with BASIC auth
      POST
    • Submit presence events
      POST
  • Occupancy
    • Occupancy Overview
    • Submit occupancy events
      POST
  • Time off
    • Submit time off updates
      POST
  • Access Credentials
    • Submit access credentials
      POST
  • Warehouse - Basic Auth
    • Warehouse Overview
    • Users
      GET
    • Locations
      GET
    • Desks
      GET
    • Bookings & Attendance
      GET
    • Presence Details
      GET
    • User Actions Log
      GET
  • Warehouse - HMAC Auth
    • Warehouse Overview
    • Users
      GET
    • Locations
      GET
    • Desks
      GET
    • Bookings & Attendance
      GET
    • Presence
      GET
    • User Actions Log
      GET

Key Access Levels

When API keys are created by Calven they have 2 distinct properties:
Key access control - which dictates the role of the key and therefore the endpoints that the key can access
Key authentication - which dictates whether the key can be used for Basic Authentication or only HMAC
The Calven API uses API keys to authenticate API requests. Your API keys carry many priviledges so please keep them secure!
To use the API you will require an API key and secret. Contact support@calven.com for assistance in getting those details. You will need to specify which type of authentication and access control you want provisioned to the key(s).

Authentication#

There are two types of authentication used on API calls in Calven
1.
Basic Authentication
2.
HMAC Authentication
Basic authentication sends the API key and secret with each API 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. This ensures that the secret remains 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.
API Keys are generated to be used only for HMAC authentication, or for both Basic and HMAC. HMAC is utilized if you are interacting with the APIs via a sophisticated client or utilizing Calven's SDKs. Basic auth is available if your tools cannot calculate an HMAC as part of the request.

Access Control#

The API keys are categorized into one of 4 roles. Once a key is generated for a specific role, it cannot be updated to a different role, a new key must be used.
The 4 roles are:
RoleDescriptionEndpoints AllowedPII Access
Submitting EventsLimited to pushing data into Calven from other systems. Does not access data within Calven.POST /v1/presence
POST /v1/occupancy
POST /v1/access-credentials
POST /v1/timeoff
POST /v1/visitor-arrival		No
Visitor Permissions OnlyLimited in scope to sending visitor arrival events. Typically used for deploying to a base-building access control system not controlled by yourself.POST /v1/visitor-arrivalNo
Data WarehouseLimited to accessing data from our warehouse for your own warehouse or BI tools.GET /v1/analytics/*Yes
All permissionsNo restrictions, used for all purposes.All endpointsYes
The /basic variants of endpoints have the same role-based access control applied to them as the HMAC endpoint.
Modified at 2025-04-03 13:54:25
Previous
Overview
Next
Basic Authentication Overview
Built with