Authentication & Authorization

Authentication

Requests made to all Honeybee Health APIs must be authorized. 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.

Additionally, the OAuth 2.0 standard defines access token scopes, used to specify the reason for which access to resources may be granted. Check specific API documentation if the Honeybee Health API used requires a scoped access token.

Using your securely stored client_id and client_secret you can obtain an access token for your account. This access token is then used to authorize requests for resources available via a Honeybee Health API.

All API requests must be made over HTTPS.

Basic steps

1. Visit the Partner Portal to obtain a client ID and client secret. You will only be able to see your secret once, so be sure to make note of it and keep it secure! Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.

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: auth.honeybeehealth.com
   Content-Type: application/x-www-form-urlencoded;charset=utf-8
   
   grant_type=client_credentials&client_id=PAE_tecHj8ib_0F7cXuq55emEdasKPJcgV3PE3Gd56Y&client_secret=jXA3jNpRnGIfE7xXONDgH8chCJZgLi8bGOIJYuVvKe0&scope=partners
   

   Access Token Response

   HTTP/1.1 200 OK
   Content-Type: application/json;charset=utf-8
   Cache-Control: no-store
   
   {
       "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 simply request another access token.