Security

Authentication

Requests made to the Partners API must be authenticated. Honeybee Health uses the OAuth 2.0 protocol to provide secure access to our APIs. OAuth 2.0 is a standard for authorization and is used to grant access to protected resources in your account.

The OAuth 2.0 specification defines different mechanisms, called "grant types," for distributing access tokens for apps. The most common grant type used for application to application communiction defined by OAuth 2.0 is called "client credentials." In this grant type, OAuth access tokens are generated in exchange for client credentials, which are client_id/client_secret pairs.

Using your client_id and client_secret you can obtain an access token for your account. This access token is then used to authenticate your requests to the API.

Basic steps

1. Visit the Partner Portal to obtain a client ID and client secret.

2. Obtain an access token from the OAuth 2.0 endpoint using your client ID and client secret.

   Before your application can access private data, it must obtain an access token that grants access to that API. A single access token can grant varying degrees of access to multiple APIs. A token is a string representing an authorization issued to the client.

   Access Token Request

   POST /oauth/token HTTP/1.1
   Host: partners.honeybeehealth.com
   Content-Type: application/x-www-form-urlencoded;charset=utf-8
   
   grant_type=client_credentials&client_id=PAE_tecHj8ib_0F7cXuq55emEdasKPJcgV3PE3Gd56Y&client_secret=jXA3jNpRnGIfE7xXONDgH8chCJZgLi8bGOIJYuVvKe0
   

   Access Token Response

   HTTP/1.1 200 OK
   Content-Type: application/json;charset=utf-8
   Cache-Control: no-store
   Pragma: no-cache
   
   {
       "access_token": "xxxxxxxxxxxxxxx",
       "token_type": "Bearer",
       "expires_in": 43200,
       "created_at": 1592972935
   }
   

3. Send the access token to an API endpoint. The access token should be sent as a Bearer token in the Authorization header of the request. The API will validate the token and grant or deny access to the resource.

4. Access tokens have a limited lifetime specified by the expires_in field. If your application needs access to a resource beyond the lifetime of a single access token, it can simple request another access token.

Webhook Security

Webhooks will include an X-Honeybee-Signature header that can be used to validate that the request was in fact made by Honeybee Health.

The signature is constructed by concatenating the request method, i.e. POST, with the url of the webhook and the url encoded payload. We will then sign this string with HMAC-SHA1 using your client_secret and finally base64 encode the result with a trailing newline character.

Perform the same steps on the receiving end to validate the signature.

A pseudo-code representation of this looks like:

base = escape(request.method + request.url + string(request.body))
key = sha256_hex_digest(your_client_secret)
X-Honeybee-Signature = base64_encode(hmac_sha1_digest(key, base) + "\n")

Examples for generating sha256_hex_digest in common languages:

Ruby

Digest::SHA256.hexdigest('your_client_secret')

Node

const crypto = require('crypto')
crypto.createHash('sha256').update('your_client_secret').digest('hex')

Python

import hashlib
hashlib.sha256('your_client_secret'.encode('utf-8')).hexdigest()

Go

package main

import (
  "crypto/sha256"
  "encoding/hex"
  "fmt"
)

func main() {
  hash := sha256.New()
  hash.Write([]byte("your_client_secret"))
  sha256_hash := hex.EncodeToString(hash.Sum(nil))
}