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.
    Previous
    Overview
    Next
    Basic Authentication Overview
    Built with