How-to make authorized Buoy API requests from an M2M app

📘

This page is only applicable to organizations in active development or with live clients.

Overview

For machine-to-machine (M2M) applications to make authorized requests to the Buoy API, the application must follow the client credentials authorization flow. This guide will walk through how an application can request and refresh M2M access tokens (Bearer tokens) to make authorized request to the Buoy API.

Making authorized requests

1. Within your M2M application, make a request to Buoy's authorization server to request an access token grant. Within the body of the POST request your application should include your Buoy API credentials (client_id and client_secret) as shown in the example below.

Python

import requests

def get_buoy_api_access_token():
    """Access Token grant for Buoy API resources.
    This is the OAuth 2.0 grant the server processes utilize in
    order to access Buoy APIs. Use this endpoint to directly request
    an access_token by using your Auth Application Credentials (a Client Id
    and a Client Secret).

    Returns:
        access_token(string)
    """
    return requests.post(
        f'https://auth.buoyhealth.com/oauth/token', # https://auth.sandbox.buoyhealth.com/oauth/token for Sandbox usage
        data={
            'client_id': BUOY_API_CLIENT_ID,
            'client_secret': BUOY_API_CLIENT_SECRET,
            'audience': 'https://api.buoyhealth.com', # https://api.sandbox.buoyhealth.com for Sandbox usage
            'grant_type': 'client_credentials',
        },
        headers={
          'content-type': 'application/json'
        }
    ).json().get('access_token')

2. The retrieved access token can be reused until its expiration date (24 hours). It is recommended that your application stores the access token in application memory or cache to be reused and avoid unnecessary access token request overhead.
3. Apply the access token to all requests made to Buoy APIs. The token should be attached to the request headers in the form of: 'Authorization': 'Bearer <access_token>.
4. Periodically or when the access token expires, your application should refresh the token by recalling the same endpoint to Buoy's Authorization Server as described in Step 1. A request to the Buoy API with an expired access token will return a 401 Unauthorized HTTP status code with the response: {"detail": "Token is invalid or expired (decode)."}