Authenticating

Calven APIs require a Bearer token to be passed in the Authentication header.

To obtain a bearer token, an API key and a secret must be used with one of two authentication endpoints.

HMAC authentication

The recommended authentication method is to use a HMAC signature. The advantage of this method is that the secret never travels "across the wire".

To perform HMAC authentication three values must be provided via a POST to the https://api.calven.com/v1/auth endpoint.

{
   "apiKey":"55DE3799-6C65-43F3-9AFB-A4725358B4FD",
   "timestamp": 1683257792,                 
   "hash":"28abb1473849dce11bde3f73c539fc6a42605a3eee6414312680bb377f430a05"
}

Property	Description
apiKey	The APIKey ID for which a token is requested
timestamp	The current unix epoch time stamp
hash	The HMAC-SHA256 hash generated from the string `<apiKey>+timestamp` using the api key secret

If authentication is successful, the response document will contain a bearer token that must be passed in the Authentication header when calling Calven APIs.

{
   "authenticated":true,
   "message":"Authentication successful",
   "token":"eyxxxx.....",
   "expiration": 1683258201
}

The token is only valid until the expiration time is reached. At that time a new token must be requested.

Note: It is important that the Content-Type header is set to application/json

Sample code

Requesting a token in Python

Requesting a token in Javascript

Requesting a token in Powershell


# Import the required modules
using module System.Security.Cryptography
using module System.Text
using module System.Net.Http

# Define the API key, secret, and timestamp
$apiKey = "YOUR_API_KEY"
$secret = "YOUR_SECRET"
$timestamp = [Math]::Floor((Get-Date -UFormat %s))

# Generate the HMACSHA256 signature
$signature = ""
$payload = "$apiKey$timestamp"
$secretBytes = [Text.Encoding]::UTF8.GetBytes($secret)
$payloadBytes = [Text.Encoding]::UTF8.GetBytes($payload)
$hmacsha256 = [HMACSHA256]::new($secretBytes)
$hashBytes = $hmacsha256.ComputeHash($payloadBytes)
foreach ($byte in $hashBytes) {
    $signature += $byte.ToString("x2")
}

# Create the HTTP client and request the token
$httpClient = [HttpClient]::new()
$tokenUrl = "https://api.calven.com/v1/auth"
# Create the JSON payload
$jsonPayload = @{
  "apiKey" = $apiKey
  "timestamp" = $timestamp
  "hash" = $signature
} | ConvertTo-Json

# Create the HTTP content
$content = [System.Net.Http.StringContent]::new($jsonPayload, [System.Text.Encoding]::UTF8, "application/json")

# Send the POST request and get the response
$response = $httpClient.PostAsync($tokenUrl, $content).Result
$token = $response.Content.ReadAsStringAsync().Result | ConvertFrom-Json | Select-Object -ExpandProperty token

# Use the token for further API requests
# ...

# END:

OAuth client credentials grant

An OAuth client credentials grant can also be used to obtain a token.

To obtain a token using this method, POST a client credentials grant request to the https://api.calven.com/v1/auth/token endpoint.

The client_id and client_secret values are included in the JSON body that is posted to this endpoint. Alternatively, they can be included in the Authorization header using HTTP basic authentication.
If the client_id and client_secret are valid, an OAuth token response document is returned:

{
  "access_token":"eyxxxxxx...",
  "expires_in":3600,
  "token_type":"Bearer"
}

The token will expire in expires_in seconds. After that time a new token must be requested.

Basic authentication

To allow systems that cannot support a two-step auth process to report presence, the /v1/presence/basic endpoint accepts basic authentication. A specific API key that is enabled for basic authentication is required. This API key cannot be used with the /v1/auth endpoints.

Contact Calven support to request a basic auth API key.

Authenticating

HMAC authentication#

Sample code#

Requesting a token in Python#

Requesting a token in Javascript#

Requesting a token in Powershell#

OAuth client credentials grant#