Bridge Health API: Authentication & Authorization

Overview

The API uses a JSON-based Bearer-token scheme. This is a machine-to-machine API: clients obtain an access token with a call to POST /auth/token, then include the access token in the Authorization header of every subsequent request. When a token expires, call POST /auth/token again with your client_key and client_secret to obtain a new token.

Request requirements

To ensure reliable delivery and support, please send well-formed, descriptive, and identifiable requests.

Header	Required	Notes
User-Agent	Yes	Use a descriptive value. Example format: <AppName>/<Version> (e.g. YourCompanyBridgeIntegration/1.0). The precise details matter less than making it intentional. Generic or default library values (e.g. python-urllib3/2.5.0) can cause requests to be rejected.
Accept	Yes	application/json
Content-Type	Yes (when body present)	application/json
Request identifier	Recommended	Include some request identifier in a header (e.g. X-Request-Id or X-Correlation-Id with a UUID) to help support troubleshoot issues.

• US IPs only: Requests are only accepted from US IP addresses. Ensure your integration runs from or egresses through US-based infrastructure.

If you receive 403 Forbidden, verify that your requests use the headers above and originate from a US IP. If the issue persists, include your request identifier when contacting Bridge for support.

Obtaining an access token

• Endpoint: POST /auth/token
• Base URL: https://sandbox-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://sandbox-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
token_type	string	Always "Bearer"

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

Example curl

curl -X POST https://sandbox-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://sandbox-api.bridgehealthhub.com
Authorization: Bearer <access_token>
Content-Type:  application/json

Example:

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

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
}