Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.maxcare.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Max AI API uses Bearer token authentication with API keys. Every request must include two required headers.

​
Required Headers

HeaderRequiredDescription
AuthorizationYesYour API key as a Bearer token: Bearer max_prd_ak_...
X-Organization-IdYesThe clinic organization ID you’re accessing

​
Example

curl -X GET "https://api.maxcare.ai/v3/patients" \
  -H "Authorization: Bearer max_prd_ak_SBA...01S" \
  -H "X-Organization-Id: 7e2c8cfe-b7a9-4deb-986d-e7012589e72b"

​
API Key Types

There are two types of API keys in the Max AI platform:

​
Account API Keys

Used by the CLI for account-level operations such as creating apps, deploying, and managing your developer account. These are generated from the developer console and are tied to your developer identity, not a specific app.

​
Data API Keys

Used by your app to access clinic data (patients, appointments, bills, etc.). Data API keys are bound to a specific app, and each key has its own set of scopes selected at creation time. The effective permissions of a key are the intersection of that key’s scopes with the permissions granted when the app is installed. Data API keys follow a prefixed format that indicates the environment:
EnvironmentPrefixExample
Productionmax_prd_ak_max_prd_ak_SBA...01S
Stagingmax_dev_ak_max_dev_ak_SBA...01S

​
Generating a Key

  1. Sign in at app.maxcare.ai
  2. Go to Marketplace > Your App > Settings
  3. Under API Keys, click Generate New Key
  4. Copy the key immediately
API keys are shown only once at creation time. Store them securely in environment variables or a secrets manager. If you lose a key, revoke it and generate a new one.

​
Key Security Best Practices

  • Never commit API keys to version control
  • Never expose keys in client-side code (JavaScript bundles, mobile apps)
  • Store keys in environment variables or a secrets manager (e.g., AWS Secrets Manager, Doppler, Vault)
  • Rotate keys periodically and immediately if compromised
  • Use separate keys for development and production

​
Organization ID

The X-Organization-Id header tells the API which clinic’s data to access. Your app can only access data from organizations (clinics) that have installed your app. To verify your access and see which organization you’re connected to: 
curl -X GET "https://api.maxcare.ai/v3/marketplace/me" \
  -H "Authorization: Bearer max_prd_ak_SBA...01S" \
  -H "X-Organization-Id: 7e2c8cfe-b7a9-4deb-986d-e7012589e72b"

​
Error Responses

When authentication fails, the API returns structured error responses:

​
401 Unauthorized

Returned when the API key is missing, invalid, or expired. 
{
  "code": "unauthorized",
  "message": "Invalid or missing API key",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
Common causes:
  • Missing Authorization header
  • Malformed Bearer token (e.g., missing Bearer prefix)
  • Revoked or expired API key

​
403 Forbidden

Returned when the API key is valid but lacks the required scope for the endpoint. 
{
  "code": "forbidden",
  "message": "Insufficient scope. Required: read:patients",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
Common causes:
  • Your app hasn’t been granted the required scope
  • The clinic hasn’t approved the scope during app installation
See Scopes for the full list of permissions and which endpoints they unlock.