Menu
GETPOST admin/apps/{app_slug}/users/ User API

API endpoint for managing app access (admin only). GET /api/admin/apps/{app_slug}/users/ POST /api/admin/apps/{app_slug}/users/

Body is validated by AppAccessCreateSerializer; its fields are not listed here.

URL

  • User APIhttps://auth.mattering.io/api/admin/apps/{app_slug}/users/

Path parameters

NameType
app_slugslug

Query parameters

NameDefault
organization_idnone

Responses

200 bare JSON object (no envelope)

[
  {
    "user_email": "...",
    "user_name": "...",
    "organization_name": "...",
    "organization_id": "...",
    "app_name": "...",
    "app_url": "...",
    "permissions": [
      "..."
    ],
    "id": "...",
    "role": "...",
    "granted_at": "2026-01-01T00:00:00Z",
    "granted_by": "...",
    "is_active": true,
    "last_accessed": "...",
    "custom_permissions": "..."
  }
]

201 bare JSON object (no envelope)

{
  "...": "..."
}

400 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
400Invalid organization_id message
403Admin access required message
404App not found message

Example

curl -X GET "https://auth.mattering.io/api/admin/apps/APP_SLUG/users/?organization_id=..." \
  -H "Authorization: Bearer $MATTERING_ACCESS_TOKEN"

Source: mattering_auth/views.py (views.AppAccessManagementView)

PUTDELETE admin/apps/{app_slug}/users/{user_id}/ User API

API endpoint for managing specific app access (admin only). PUT /api/admin/apps/{app_slug}/users/{user_id}/ DELETE /api/admin/apps/{app_slug}/users/{user_id}/

Body is validated by AppPermissionUpdateSerializer; its fields are not listed here.

URL

  • User APIhttps://auth.mattering.io/api/admin/apps/{app_slug}/users/{user_id}/

Path parameters

NameType
app_slugslug
user_iduuid

Query parameters

NameDefault
organization_idnone

Body keys (JSON)

KeyRequiredDefault
organization_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)

{
  "...": "..."
}

200 bare JSON object (no envelope)

{
  "message": "App access revoked successfully"
}

400 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
403Admin access required message
404App access not found message
404App access not found for this organization message
404App not found message

Example

curl -X PUT "https://auth.mattering.io/api/admin/apps/APP_SLUG/users/USER_ID/" \
  -H "Authorization: Bearer $MATTERING_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "organization_id": "..."
}'

Source: mattering_auth/views.py (views.AppAccessDetailManagementView)

GET apps/ User API

API endpoint for listing apps. GET /api/apps/

Accepts JWT (Bearer) or API-key (X-API-Key / X-API-Secret) authentication. Uses the global DEFAULT_AUTHENTICATION_CLASSES (JWT + API-key + OAuth2).

URL

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

Responses

200 bare JSON object (no envelope)

[
  {
    "user_count": 0,
    "id": "...",
    "name": "...",
    "slug": "...",
    "url": "...",
    "description": "...",
    "icon": "...",
    "is_active": true,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "settings": {
      "...": "..."
    },
    "price_per_seat": "...",
    "free_seat_limit": "...",
    "stripe_price_id": "...",
    "has_free_tier": true,
    "coming_soon": "...",
    "app_class": "...",
    "active_on_toolbar": "...",
    "icon_kind": "...",
    "icon_paths": "..."
  }
]

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/apps/" \
  -H "Authorization: Bearer $MATTERING_ACCESS_TOKEN"

Source: mattering_auth/views.py (views.AppListView)

GET apps/{app_slug}/ User API

API endpoint for app details. GET /api/apps/{slug}/

Public endpoint requiring API key authentication. Requires: X-API-Key and X-API-Secret headers.

Authentication: X-API-Key and X-API-Secret headers.

URL

  • User APIhttps://auth.mattering.io/api/apps/{app_slug}/

Path parameters

NameType
app_slugslug

Responses

200 bare JSON object (no envelope)

{
  "user_count": 0,
  "id": "...",
  "name": "...",
  "slug": "...",
  "url": "...",
  "description": "...",
  "icon": "...",
  "is_active": true,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "settings": {
    "...": "..."
  },
  "price_per_seat": "...",
  "free_seat_limit": "...",
  "stripe_price_id": "...",
  "has_free_tier": true,
  "coming_soon": "...",
  "app_class": "...",
  "active_on_toolbar": "...",
  "icon_kind": "...",
  "icon_paths": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
404App not found message

Example

curl -X GET "https://auth.mattering.io/api/apps/APP_SLUG/" \
  -H "Authorization: Bearer $MATTERING_ACCESS_TOKEN"

Source: mattering_auth/views.py (views.AppDetailView)

POST apps/{app_slug}/check-permission/ User API

API endpoint for checking app permissions. POST /api/apps/{app_slug}/check-permission/

Optional tier_required body field gates the response on the organization's :attr:Organization.subscription_tier. Used by the MCP edge (packages/mattering_mcp_base.MatteringTokenVerifier) to enforce that paid-only integrations refuse free-tier orgs even when their AppAccess row is still active: free users keep web-app access, but lose MCP / API features that require a paid plan.

Currently supports tier_required="paid". Unset / empty preserves backward-compatible behavior (no tier check).

Structured reason codes returned on 403 (consumed by packages/mattering_mcp_base.MatteringTokenVerifier for MCP 401 bodies):

* no_app_access_in_org: user has no active seat for this app in the requested organization (most common MCP misconfiguration: wrong org selected during OAuth consent). * no_app_access: user has no active seat for this app anywhere. * tier_required_paid: org has a seat but subscription tier is too low.

URL

  • User APIhttps://auth.mattering.io/api/apps/{app_slug}/check-permission/

Path parameters

NameType
app_slugslug

Body keys (JSON)

KeyRequiredDefault
organization_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.

Example

curl -X POST "https://auth.mattering.io/api/apps/APP_SLUG/check-permission/" \
  -H "Authorization: Bearer $MATTERING_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "organization_id": "..."
}'

Source: mattering_auth/views.py (views.AppPermissionCheckView)

GET apps/{slug}/glyph/ Service tier

GET /api/internal/apps/<slug>/glyph/ returns {slug, icon_kind, icon_paths}.

icon_paths is always the stroked 24x24 glyph, even when icon_kind is brand. The kind only decides what the *launcher tile* draws; the favicon always uses the stroked paths, because the brand mark is 103x103 with a white plate and interior detail that collapses into a white square at 16px.

URL

  • Service tierhttps://auth.mattering.io/api/internal/apps/{slug}/glyph/

Path parameters

NameType
slugslug

Responses

200 bare JSON object (no envelope)

{
  "slug": "...",
  "icon_kind": "...",
  "icon_paths": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
404app_not_found

Example

curl -X GET "https://auth.mattering.io/api/internal/apps/SLUG/glyph/" \
  -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/internal_app_views.py (internal_app_views.app_glyph)

GET apps/{slug}/orgs/{org_id}/access/ Service tier

GET /api/internal/apps/<slug>/orgs/<org_id>/access/?emails=a@x,b@y

Batch seat check for the Premier dual check (Workspace Member Directory Template ยง3): returns the subset of emails holding an ACTIVE seat (AppAccess) for this app in this org, as {app, organization_id, emails: [lowercased, sorted]}.

Identity is email, matched case-insensitively, never auth pks. All Apps Pass holders are covered because the pass materialises per-app AppAccess rows, and a revoked app (all_apps_excluded) is an inactive row. Orgs on the plan catalog also count every plan seat holder (one seat opens every app; the migration retired the per-app rows). Only seat rows are consulted: entitlement-gated (Bonus/Engine) apps have no seats and must not call this. Unknown app returns 404 app_not_found.

URL

  • Service tierhttps://auth.mattering.io/api/internal/apps/{slug}/orgs/{org_id}/access/

Path parameters

NameType
slugslug
org_iduuid

Query parameters

NameDefault
emailsnone

Responses

200 bare JSON object (no envelope)

{
  "app": "...",
  "organization_id": "...",
  "emails": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400too_many_emails
404app_not_found

Example

curl -X GET "https://auth.mattering.io/api/internal/apps/SLUG/orgs/ORG_ID/access/?emails=..." \
  -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/internal_app_views.py (internal_app_views.app_seat_holders)

GET user/apps/ User API

API endpoint for user's app access. GET /api/user/apps/?organization_id=<uuid>

Returns seat-based access (AppAccess rows) plus computed access to Bonus apps the user is entitled to via an organization's paid entitlement.

URL

  • User APIhttps://auth.mattering.io/api/user/apps/

Query parameters

NameDefault
organization_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
400Invalid organization_id message

Example

curl -X GET "https://auth.mattering.io/api/user/apps/?organization_id=..." \
  -H "Authorization: Bearer $MATTERING_ACCESS_TOKEN"

Source: mattering_auth/views.py (views.UserAppAccessListView)

GETPUT user/apps/{app_slug}/ User API

API endpoint for specific user app access. GET /api/user/apps/{app_slug}/ PUT /api/user/apps/{app_slug}/

Body is validated by AppPermissionUpdateSerializer; its fields are not listed here.

URL

  • User APIhttps://auth.mattering.io/api/user/apps/{app_slug}/

Path parameters

NameType
app_slugslug

Query parameters

NameDefault
organization_idnone

Body keys (JSON)

KeyRequiredDefault
organization_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)

{
  "...": "..."
}

400 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
404App access not found message
404App access not found for this organization message
404App not found message

Example

curl -X PUT "https://auth.mattering.io/api/user/apps/APP_SLUG/" \
  -H "Authorization: Bearer $MATTERING_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "organization_id": "..."
}'

Source: mattering_auth/views.py (views.UserAppAccessDetailView)

All Auth resources
Start Free Explore our Products