Bridge Health API: Authentication & Authorization

Overview

The API uses a JSON-based Bearer-token scheme. Clients obtain an access token with a single call to POST /auth/token, then include the access token in the Authorization header of every subsequent request.

Obtaining an access token

• Endpoint: POST /auth/token
• Base URL: https://api.bridgehealthhub.com
• Content-Type: application/json
• Auth on this call: None (uses the client_key / client_secret pair instead)

Request body (schema)

Field	Type	Required	Notes
client_key	string	Yes	Issued by Bridge Health
client_secret	string	Yes	Keep secret—never embed in publicly shipped code

POST https://api.bridgehealthhub.com/auth/token
Content-Type: application/json

{
  "client_key":    "<your_client_key>",
  "client_secret": "<your_client_secret>"
}

Successful response 200 OK

Field	Type	Notes
access_token	string (JWT)	Send in Authorization: Bearer …
expires_in	integer	Lifetime of the access token in seconds
refresh_token	string (JWT)	Use to obtain a new access token without re-authenticating
token_type	string	Always "Bearer"

{
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR …",
        "expires_in": 599,
        "refresh_token": "eyJhbGciOiJIUzI1NiIsInR …",
        "token_type": "Bearer"
    },
    "message": "Success",
    "success": true
}

Example curl

curl -X POST https://api.bridgehealthhub.com/auth/token \
  -H "Content-Type: application/json" \
  -d '{
        "client_key":    "<your_client_key>",
        "client_secret": "<your_client_secret>"
      }'

Using the access token

Include the token in every request:

POST /enroll
Host:   https://api.bridgehealthhub.com
Authorization: Bearer <access_token>
Content-Type:  application/json

Example:

curl https://api.bridgehealthhub.com/enroll \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "thcoPatientID": "THCO 9",
    "cboID": 1,
    "pharmacyID": "1",
    "insuranceType": "Commercial",
    "zipCode": "75034"
}

Refreshing an Expired Token

Token lifetime & Refresh Flow:

Step	Action
1	Track the expires_in value returned with the access token.
2	When (or just before) it expires, call POST /auth/token/refresh (confirm exact path with backend; common variant is /auth/refresh), sending the refresh_token in the body or as Authorization: Bearer (implementation-specific).
3	The server returns a fresh access_token / expires_in. Keep using your original refresh_token unless the response supplies a new one.

When the expires_in has elapsed, call /auth/refresh:

POST https://api.bridgehealthhub.com/auth/refresh
Authorization: Bearer <refresh_token>

The server returns a new access_token. If the call fails with 401 or 403, you must repeat the original /auth/token request with client_key & client_secret.

Authentication Errors

401 Unauthorized

This error response is presented when the client_key or client_secret in the /auth/token request is incorrect.

{
    "error": {
        "code": "UNAUTHORIZED",
        "details": "Invalid credentials"
    },
    "message": "Unauthorized",
    "success": false
}

400 Bad Request

This error response is presented when one of the required fields in the body of the /auth/token request (either client_key or client_secret) is missing.

{
    "error": {
        "code": "BAD_REQUEST",
        "details": "Invalid client key or secret"
    },
    "message": "Bad request",
    "success": false
}