Authentication

You'll need to authenticate your requests to access any of the endpoints in the Avon Health API. You will authenticate with both an organization-level client ID and secret as well as a user-level API key. In this guide, we'll look at how authentication works. Avon Health uses OAuth2 with a token to authenticate your API requests.

OAuth2 with bearer token and JWT

When establishing a connection using OAuth2, you will need:

  • Client ID
  • Client secret
  • UserID
  • Secret key

The client ID and client secret will be used to authenticate your organization. The user ID and secret key will be used to authenticate the user.

You will use your organization-level client ID and secret to generate an access token. You can generate the access token using the /auth/token endpoint.

You will use your userID and secret key to generate a JWT. Here's an example of how to generate a JWT.

Example request to generate JWT

import * as jose from "jose";

const secretKey = Buffer.from( {{secretKey}} );

const token = await new jose.SignJWT({ id: {{userID}} }) // details to encode in the token
  .setProtectedHeader({ alg: "HS256" }) // algorithm
  .setIssuedAt()
  .setIssuer("avonhealth") // issuer
  .setAudience("avonhealth") // audience
  .setExpirationTime(1697684096000) // token expiration time, e.g., "1 day"
  .sign(secretKey); // secretKey generated from previous step

Finally, here's how to add the token and jwt to the request header using cURL:

Example request with bearer token

curl https://{{base_subdomain}}.avonhealth.com/v2/patients \
  -H "Authorization: Bearer {{token}}"
  -H "x-jwt: {{jwt}}"

When using the staging account, also pass in the account: {{accountID}} header.

Example request with bearer token

curl https://{{base_subdomain}}.avonhealth.com/v2/patients \
  -H "Authorization: Bearer {{token}}"
  -H "x-jwt: {{jwt}}"
  -H "account: {{accountID}}"

Always keep your token and API key safe and ask to reset it if you suspect it has been compromised.