GET
entitlements/
User API
GET /api/entitlements/?organization_id=... (member of that org).
URL
- User APIhttps://auth.mattering.io/api/entitlements/
Query parameters
| Name | Default |
organization_id | none |
refresh | none |
Responses
200 bare JSON object (no envelope)
...
304 bare JSON object (no envelope)
{}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 403 | not_a_member |
| 403 | user authentication required message |
| 404 | Organization not found message |
Example
curl -X GET "https://auth.mattering.io/api/entitlements/?organization_id=...&refresh=..." \
-H "Authorization: Bearer $MATTERING_ACCESS_TOKEN"
Source: mattering_auth/entitlement_views.py (entitlement_views.EntitlementsView)
GET
entitlements/
Service tier
GET /api/internal/entitlements/?organization_id=...[&user_email=...] (X-Internal-Secret).
URL
- Service tierhttps://auth.mattering.io/api/internal/entitlements/
Query parameters
| Name | Default |
organization_id | none |
refresh | none |
user_email | none |
user_id | none |
Responses
200 bare JSON object (no envelope)
{
"...": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 404 | Organization not found message |
Example
curl -X GET "https://auth.mattering.io/api/internal/entitlements/?organization_id=...&refresh=...&user_email=..." \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: mattering_auth/entitlement_views.py (entitlement_views.internal_entitlements)
POST
entitlements/seats/
User API
POST /api/entitlements/seats/ {organization_id, user_id | user_email, action: assign|revoke, add_seat?}.
Org admins only. Active seats may not exceed the plan's seats (400 no_seats_left): Free includes its max seats (or every grandfathered seat after migrate_to_plans); paid plans their billed quantity. On a Free org that never assigned seats, the first members by join date are made explicit seats before the change applies.
add_seat (assign only): when every seat is taken on a paid plan, buy one more on the Stripe subscription (prorated, charged now; see plan_billing.add_paid_seat) and give it to the member. Needs billing permission. Free answers 402 plan_upgrade_required. reserved (with add_seat) counts seats held for pending invites as taken.
URL
- User APIhttps://auth.mattering.io/api/entitlements/seats/
Body keys (JSON)
| Key | Required | Default |
action | optional or conditional | none |
add_seat | optional or conditional | none |
organization_id | optional or conditional | none |
reserved | optional or conditional | none |
user_email | optional or conditional | none |
user_id | optional or conditional | none |
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200 bare JSON object (no envelope)
{
"success": true,
"action": "...",
"user_id": "...",
"email": "...",
"added_seat": true,
"seats": {
"quantity": "...",
"used": "..."
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | action must be assign or revoke message |
| 400 | no_seats_left |
| 400 | not_org_member |
| 403 | billing_permission_required |
| 403 | forbidden |
| 403 | user authentication required message |
| 404 | Organization not found message |
Example
curl -X POST "https://auth.mattering.io/api/entitlements/seats/" \
-H "Authorization: Bearer $MATTERING_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"action": "...",
"add_seat": "...",
"organization_id": "...",
"reserved": "...",
"user_email": "...",
"user_id": "..."
}'
Source: mattering_auth/entitlement_views.py (entitlement_views.SeatAssignView)
GET
plans/
User API
GET /api/plans/ returns {plans: [...current versions in catalog order...]}. Public.
URL
- User APIhttps://auth.mattering.io/api/plans/
Responses
200 bare JSON object (no envelope)
{
"plans": [
{
"key": "...",
"version": "...",
"name": "...",
"price_cents_monthly": "...",
"price_cents_annual": "...",
"min_seats": 0,
"max_seats": 0,
"ai_credits_per_seat": "...",
"ai_credits_org_base": "...",
"runs_per_seat": "...",
"runs_org_base": "...",
"limits": {
"...": "..."
},
"features": {
"...": "..."
}
}
]
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Example
curl -X GET "https://auth.mattering.io/api/plans/" \
-H "Authorization: Bearer $MATTERING_ACCESS_TOKEN"
Source: mattering_auth/entitlement_views.py (entitlement_views.plans_list)