Skip to main content

​
Scopes

API keys are issued with specific scopes that control which endpoints your app can access. Each endpoint requires a specific scope.

​
Available Scopes

ScopeDescriptionEndpoints
read:marketplaceAccess app and organization infoGET /marketplace/me
read:patientsRead patient recordsGET /patients, GET /patients/:id
read:appointmentsRead appointment dataGET /appointments, GET /appointments/:id
read:providersRead provider informationGET /providers, GET /providers/:id
read:facilitiesRead facility detailsGET /facilities, GET /facilities/:id
read:billsRead billing dataGET /bills, GET /bills/:id
read:claimsRead claims dataGET /claims, GET /claims/:id
read:inventoryRead inventory changes and stock levelsGET /inventory/changes, GET /inventory/changes/:id, GET /inventory/changes/:id/products, GET /inventory/stock-levels
read:productsRead product catalogGET /inventory/products, GET /inventory/products/:id

​
How Scopes Work

When a clinic installs your marketplace app, they grant specific scopes based on your app’s requirements. Your API key will only work for endpoints matching those granted scopes. If you call an endpoint without the required scope, you’ll receive a 403 Forbidden response: 
{
  "code": "forbidden",
  "message": "Insufficient scope. Required: read:patients",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

​
Checking Your Scopes

Use the /marketplace/me endpoint to see which scopes your API key has: 
curl -X GET "https://api.maxcare.ai/external/v1/marketplace/me" \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "X-Organization-Id: org_abc123"
The response includes your app’s granted scopes in the data.app.scopes array.