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

import hashlib
import hmac
import time
import requests

api_key = "api key"
secret_key = "api key secret"
timestamp = int(time.time())

message = api_key + str(timestamp)

hmac_signature = hmac.new(
    secret_key.encode(), message.encode(), hashlib.sha256
).hexdigest()

url = "https://api.calven.com/v1/auth"
payload = {
  "apiKey": api_key, 
  "timestamp": timestamp, 
  "hash": hmac_signature
  }

headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)

token = response.json()["token"]

Requesting a token in Javascript

const crypto = require('crypto')

const apiKey = 'your-api-key'
const timestamp = Math.floor(Date.now().getTime() / 1000.0)
const secret = 'your-secret'

const hmac = crypto.createHmac('sha256', secret)
hmac.update(apiKey + timestamp)
const signature = hmac.digest('hex')

// Make a request to obtain a token using the generated signature
// You can use any HTTP library of your choice, such as axios or node-fetch
// Here's an example using axios:
const axios = require('axios')

axios
  .post('https://api.calven.com/v1/auth', {
    apiKey,
    timestamp,
    signature,
  })
  .then((response) => {
    const token = response.data.token
    // Do something with the obtained token
  })
  .catch((error) => {
    // Handle any errors
  })

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.