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
Query parameters
| Name | Default |
organization_id | none |
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
| Status | Code |
| 400 | Invalid organization_id message |
| 403 | Admin access required message |
| 404 | App 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
| Name | Type |
app_slug | slug |
user_id | uuid |
Query parameters
| Name | Default |
organization_id | none |
Body keys (JSON)
| Key | Required | Default |
organization_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)
{
"...": "..."
}
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
| Status | Code |
| 403 | Admin access required message |
| 404 | App access not found message |
| 404 | App access not found for this organization message |
| 404 | App 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
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
| Status | Code |
| 404 | App 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
Body keys (JSON)
| Key | Required | Default |
organization_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.
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
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
| Status | Code |
| 404 | app_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
| Name | Type |
slug | slug |
org_id | uuid |
Query parameters
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
| Status | Code |
| 400 | too_many_emails |
| 404 | app_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
| Name | Default |
organization_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 |
| 400 | Invalid 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
Query parameters
| Name | Default |
organization_id | none |
Body keys (JSON)
| Key | Required | Default |
organization_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)
{
"...": "..."
}
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
| Status | Code |
| 404 | App access not found message |
| 404 | App access not found for this organization message |
| 404 | App 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)