Calven API Keys
Integrate Calven with other tools and services your organization uses by setting up API keys
Overview
Each API key is granted a fixed set of permissions at the time it's created. These permissions determine exactly what the key is allowed to do (i.e. writing user attributes or writing visitor arrivals). A key's secret is shown only once during creation, so make sure to store it securely straight away.
Viewing your API keys
Go to API Keys in your admin settings to see all keys created for your organization. Each key card shows:
- Name: a label to help identify what the key is used for
- Key ID: a unique identifier for the key
- Permissions: the scopes granted to that key
- Created by: who created the key and when
- Updated by: who last modified the key and when (if applicable)
Creating an API key
- Go to API Keys in your admin settings.
- Select + Create API key.
- In the Name field, give the key a descriptive name so you and your team can identify its purpose later.
- Select Select permissions and check the boxes for each permission the key needs (see Permissions below). Only grant what the integration actually requires.
- If the integration needs HTTP Basic Authentication, turn on the Basic auth toggle. Otherwise leave it off.
- Select Create (this stays disabled until a name and at least one permission are set). Select Cancel to discard the key instead.
An API key's secret will be displayed once. Copy and store it in a secure location (such as a password manager or secrets vault) before closing the dialog. Calven does not store or display the secret again.
Permissions
Permissions are granted individually and scoped to specific actions. Each one appears in the picker with a short description of what it allows. Available permissions include:
| Permission | What it allows |
|---|---|
| Write group hierarchy relationships | Writing group hierarchy relationships data for directory management |
| Write user attributes | Writing user attributes via external API onto the SCIM user document |
| Read events | Reading event data |
| Read groups | Reading group data |
| Write location occupancy | Submitting occupancy events |
| Read locations | Reading location data |
| Read parking bookings | Reading parking booking data |
| Write user access credentials | Creating and updating user access credentials |
| Read user bookings | Reading user booking data |
| Write user plans | Submitting user plan changes |
| Read user presence | Reading user presence data |
| Write user presence | Submitting user presence events |
| Read user profiles | Reading user profile data |
| Write visitor arrivals | Submitting visitor arrival events |
This list reflects what's currently available in the permissions picker, but new permissions may be added over time — check the picker itself for the most current options.
Managing existing keys
Use the ⋮ menu on a key's card to manage it. Two actions are available:
- Rotate secret: issues a new secret for the key while keeping its name, ID, and permissions the same. Use this if a secret may have been exposed, or as part of routine credential hygiene. The old secret stops working once rotated, so update any integration using this key with the new secret right away.
- Revoke: permanently disables the key. Any integration still using it will immediately lose access.
Because both actions can break a live integration, confirm nothing depends on the key's current secret (for rotation) or the key itself (for revocation) before proceeding.
If you have questions about setting up an integration with a Calven API key, contact Calven support or refer to the API documentation.