Skip to main content
Scopes are permissions that control which API endpoints your app can access. When a clinic installs your app, they grant the scopes your app has requested.

​
How Scopes Work

  1. When you create your app, you declare which scopes it needs
  2. When a clinic installs your app, they review and approve those scopes
  3. Your API key inherits the approved scopes
  4. Each API endpoint checks for the required scope before returning data
If you call an endpoint without the required scope, you’ll receive a 403 Forbidden response.

​
Available Scopes

​
Patient Data

ScopeEndpointsDescription
read:patientsGET /v1/patientsList patients with search and pagination
GET /v1/patients/{id}Get a specific patient by ID

​
Appointments

ScopeEndpointsDescription
read:appointmentsGET /v1/appointmentsList appointments with filters
GET /v1/appointments/{id}Get a specific appointment by ID

​
Providers

ScopeEndpointsDescription
read:providersGET /v1/providersList providers
GET /v1/providers/{id}Get a specific provider by ID

​
Facilities

ScopeEndpointsDescription
read:facilitiesGET /v1/facilitiesList facilities
GET /v1/facilities/{id}Get a specific facility by ID

​
Billing

ScopeEndpointsDescription
read:billsGET /v1/billsList bills with pagination
GET /v1/bills/{id}Get detailed bill with line items and coding groups

​
Claims

ScopeEndpointsDescription
read:claimsGET /v1/claimsList claims with pagination
GET /v1/claims/{id}Get detailed claim with insurance info

​
Inventory

ScopeEndpointsDescription
read:inventoryGET /v1/inventory/changesList inventory changes
GET /v1/inventory/changes/{id}Get a specific inventory change
GET /v1/inventory/changes/{id}/productsGet products for an inventory change
GET /v1/inventory/stock-levelsGet current stock levels
read:productsGET /v1/inventory/productsList products in the catalog
GET /v1/inventory/products/{id}Get a specific product

​
Marketplace

ScopeEndpointsDescription
read:marketplaceGET /v1/marketplace/meGet your app’s identity and organization info

​
Checking Your Scopes

Use the /v1/marketplace/me endpoint to see which scopes your API key currently has: 
curl -X GET "https://api.maxcare.ai/v1/marketplace/me" \
  -H "Authorization: Bearer max_prd_ak_SBA...01S" \
  -H "X-Organization-Id: org_abc123"
The response includes your granted scopes: 
{
  "code": "success",
  "data": {
    "app": {
      "id": "app_01J5K8N2XRQV3M7YGWT4HB6E9C",
      "slug": "my-healthcare-app",
      "liveVersionId": "ver_01J5K8N2XRQV3M7YGWT4HB6E9C"
    },
    "organization": {
      "id": "org_abc123",
    },
    "scopes": [
      "read:patients",
      "read:appointments",
      "read:providers",
      "read:bills",
      "read:claims"
    ]
  }
}

​
Insufficient Scope Error

If you call an endpoint without the required scope: 
{
  "code": "forbidden",
  "message": "Insufficient scope. Required: read:patients",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
To resolve this, update your app’s requested scopes in the Max AI dashboard and have the clinic re-approve the updated permissions.