Menu
GET entitlements/ User API

GET /api/entitlements/?organization_id=... (member of that org).

URL

  • User APIhttps://auth.mattering.io/api/entitlements/

Query parameters

NameDefault
organization_idnone
refreshnone

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

StatusCode
403not_a_member
403user authentication required message
404Organization 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

NameDefault
organization_idnone
refreshnone
user_emailnone
user_idnone

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

StatusCode
404Organization 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)

KeyRequiredDefault
actionoptional or conditionalnone
add_seatoptional or conditionalnone
organization_idoptional or conditionalnone
reservedoptional or conditionalnone
user_emailoptional or conditionalnone
user_idoptional or conditionalnone

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

StatusCode
400action must be assign or revoke message
400no_seats_left
400not_org_member
403billing_permission_required
403forbidden
403user authentication required message
404Organization 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)

All Auth resources
Start Free Explore our Products