If you were provided a JWT at account setup rather than an API client id and client secret, please refer to instructions for legacy token authentication.

Garner APIs authenticate with OAuth 2.0 access tokens. You will be provided an API client ID and API client secret during account setup. The client ID and client secret can be exchanged for an access token which in turn authenticates your app when making calls to Garner's APIs.

To obtain an access token, make a request to the POST oauth2/token/ endpoint. In the request body, include the client_id, client_secret, and grant_type=client_credentials. This response will contain an access_token, the token_type which will always be "Bearer", and expires_in which is the lifetime in seconds of the token.

The access token can be used to authenticate with Garner's APIs. When making a request, provide the access token as a bearer token in the Authorization header.

For example,

JavaScript

/* Get the token */
const { access_token, token_type, expires_in } = await fetch('https://api.getgarner.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: '<YOUR_API_CLIENT_ID_HERE>',
    client_secret: '<YOUR_API_CLIENT_SECRET_HERE>',
  }),
}).then(r => r.json());


/* Use the token */
const { providers } = fetch(
  'https://api.getgarner.com/providers',
  {
    method: 'GET',
    headers: {'Authorization': `Bearer ${<YOUR_ACCESS_TOKEN_HERE>}`},
    query: ...
  },
).then(response => response.json());

cURL

# Get the token
curl --location 'https://api.garner.health/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<YOUR_API_CLIENT_ID_HERE' \
--data-urlencode 'client_secret=<YOUR_API_CLIENT_SECRET_HERE>'

# Use the token
curl -G https://api.getgarner.com/providers -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN_HERE>'

Managing the access token

The access token will only be valid for 15 minutes. We recommend caching the token in your application so that it can be reused up to its expiration. This can be managed by the app programmatically by implementing a GarnerTokenClient class like the following:

class GarnerTokenClient {
  /** Cached access token */
  private currentToken: string | undefined;
  /** Time at which the cached token expires */
  private expirationTime: number | undefined;

  /** 
  *  Fetches a new access token from the `POST /oauth2/token` endpoint,
  *  then caches the token and its expiration time.
  *  Returns a promise that resolves to the newly fetched access token
  */
  private async fetchNewToken(): Promise<string> {
    const currentTime = Date.now();
    const { access_token: accessToken, expires_in: expiresIn } = await fetch('https://api.getgarner.com/oauth2/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'client_credentials',
        client_id: '<YOUR_API_CLIENT_ID_HERE>',
        client_secret: '<YOUR_API_CLIENT_SECRET_HERE>',
      }),
    }).then(r => r.json());
    // Cache the access token
    this.currentToken = accessToken;
    // Set the expiration time as the current time plus the number of ms until the token expires. Subtract a 15 second buffer to account for lag.
    this.expirationTime = (currentTime + expiresIn * 1000) - 15000; 
    return accessToken;
  }

  /** 
  *  Returns the cached access token if it is valid. 
  *  Otherwise, fetches a new token.
  */
  async getToken(): Promise<string> {
    if (this.currentToken && this.expirationTime && Date.now() < this.expirationTime) {
      return this.currentToken;
    }
    return await this.fetchNewToken();
  }
}

Then when making a request to Garner's APIs you can use the response of getToken() from an instance of the GarnerTokenClient class as your token.

For example,

const garnerTokenClient = new GarnerTokenClient();

fetch('https://api.getgarner.com/providers',
  {
    method: 'GET',
    headers: {'Authorization': `Bearer ${await garnerTokenClient.getToken()}`},
    query: ...
  },
);

If you were provided an API client id and client secret at account setup rather than a token, please refer to instructions for OAuth2.0 authentication.

Authenticating is done with an JSON Web Token (JWT) provided as a Bearer token to the Authorization header. You will have received a token during account setup.

For example,

curl -G https://api.getgarner.com -H 'Authorization: Bearer <YOUR_API_TOKEN_HERE>'