Skip to main content
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/v1/patients" \
  -H "Authorization: Bearer max_prd_ak_SBA...01S" \
  -H "X-Organization-Id: org_abc123"

​
API Keys

API keys authenticate your app and determine which scopes (permissions) are available. Each key is bound to a specific app.

​
Key Format

API keys follow the format: 
max_prd_ak_<random_string>

​
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/v1/marketplace/me" \
  -H "Authorization: Bearer max_prd_ak_SBA...01S" \
  -H "X-Organization-Id: org_abc123"

​
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.