GET
mcp/principal/
User API
No auth required
Identity + org context for a Mattering-issued token, any audience.
GET /api/mcp/principal/
Backs the shared MCP whoami / get_account / get_organization / list_organizations tools (mattering_mcp_base.common_tools).
Why a dedicated endpoint instead of reusing /api/profile/ + /api/organizations/: MCP access tokens are minted with aud set to the MCP *resource* URL (RFC 8707), not the platform audience. The normal DRF IsAuthenticated API authenticates against the platform audience and would reject an MCP token. Here we validate the bearer with :meth:JWTHandler.validate_token (audience=None), which accepts any *legitimate* Mattering audience: including the per-resource MCP audiences in MCP_ALLOWED_RESOURCES: because auth is the issuer of all of them. We then resolve the principal off the verified sub claim and return account + org context in one round-trip.
Security: this is read-only and only ever returns data scoped to the user the token already proves you are. It never widens access.
URL
- User APIhttps://auth.mattering.io/api/mcp/principal/
Responses
200 bare JSON object (no envelope)
{
"account": {
"user_id": "...",
"email": "...",
"email_verified": true,
"display_name": "...",
"username": "..."
},
"active_organization": {
"id": "...",
"name": null,
"role": null,
"is_active": true,
"note": "Token's org is not in the user's active memberships."
},
"organizations": [
"..."
],
"org_count": 0
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 401 | invalid_token |
| 401 | missing_bearer |
| 404 | user_not_found |
Example
curl -X GET "https://auth.mattering.io/api/mcp/principal/" \
-H "Authorization: Bearer $MATTERING_ACCESS_TOKEN"
Source: mattering_auth/views.py (views.MCPPrincipalContextView)
GET
organizations/
User API
API endpoint for listing user's organizations. GET /api/organizations/
URL
- User APIhttps://auth.mattering.io/api/organizations/
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).
Example
curl -X GET "https://auth.mattering.io/api/organizations/" \
-H "Authorization: Bearer $MATTERING_ACCESS_TOKEN"
Source: mattering_auth/views.py (views.OrganizationListView)
GET
organizations/
Service tier
GET /api/internal/organizations/ returns {"organizations": [{id, name}]}.
Migration-support endpoint: lets the workspace reconciliation tool discover every org so it can iterate per-org space inventories across apps. Guarded by the internal secret.
URL
- Service tierhttps://auth.mattering.io/api/internal/organizations/
Query parameters
| Name | Default |
active_only | none |
Responses
200 bare JSON object (no envelope)
{
"organizations": [
{
"id": "...",
"name": "..."
}
]
}
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/internal/organizations/?active_only=..." \
-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_workspace_views.py (internal_workspace_views.list_all_organizations)
POST
organizations/create/
User API
POST /api/organizations/create/ Body: { name, default_workspace_name? } Creates a new organization and makes the current user its primary owner.
When default_workspace_name is provided, the org's default workspace is bootstrapped (is_default=True) with the creator seated as its owner-role member, and returned as default_workspace in the response. When omitted, NO workspace is auto-created: the Phase-2 registration/onboarding UI supplies the name later.
URL
- User APIhttps://auth.mattering.io/api/organizations/create/
Body keys (JSON)
| Key | Required | Default |
default_workspace_name | optional or conditional | none |
name | 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
201 bare JSON object (no envelope)
{
"success": true,
"organization": {
"...": "..."
},
"default_workspace": {
"...": "..."
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | Organization name is required message |
| 400 | Organization name must be 100 characters or less message |
| 400 | Workspace name must be 255 characters or less message |
Example
curl -X POST "https://auth.mattering.io/api/organizations/create/" \
-H "Authorization: Bearer $MATTERING_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"default_workspace_name": "...",
"name": "..."
}'
Source: mattering_auth/views.py (views.OrganizationCreateView)
GETDELETE
organizations/{org_id}/
User API
API endpoint for organization details. GET /api/organizations/{id}/ DELETE /api/organizations/{id}/
URL
- User APIhttps://auth.mattering.io/api/organizations/{org_id}/
Path parameters
Body keys (JSON)
| Key | Required | Default |
confirm_name | 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)
{
"id": "...",
"member_count": 0,
"owner_email": "...",
"name": "...",
"created_at": "2026-01-01T00:00:00Z",
"settings": {
"...": "..."
},
"timezone": "..."
}
200 bare JSON object (no envelope)
{
"success": true,
"state": "...",
"scheduled_for": "2026-01-01T00:00:00Z",
"message": "...",
"organization_id": "...",
"remaining_organizations": "...",
"suggested_organization_id": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | Organization name does not match. Deletion cancelled. message |
| 403 | Only organization owners can delete an organization message |
| 404 | Organization not found or access denied message |
Example
curl -X DELETE "https://auth.mattering.io/api/organizations/ORG_ID/" \
-H "Authorization: Bearer $MATTERING_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"confirm_name": "..."
}'
Source: mattering_auth/views.py (views.OrganizationDetailView)
GET
organizations/{org_id}/branding/
Service tier
GET /api/internal/organizations/<uuid:org_id>/branding/
-> {enabled, accent, logo_url}. enabled is False (with empty values) when the org is unknown, inactive, or not whitelabel-entitled: callers can treat the response shape as constant and never branch on 404.
URL
- Service tierhttps://auth.mattering.io/api/internal/organizations/{org_id}/branding/
Path parameters
Responses
200 bare JSON object (no envelope)
{
"enabled": false,
"accent": "...",
"logo_url": "..."
}
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/internal/organizations/ORG_ID/branding/" \
-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_branding_views.py (internal_branding_views.org_branding)
GET
organizations/{org_id}/workspaces/
Service tier
GET /api/internal/organizations/<uuid:org_id>/workspaces/
Returns {"workspaces": [...]} for the org. Optional ?user_id= or ?email= restricts to workspaces that user is a member of, and each entry then carries the user's role (thin-mirror apps render role badges without a local membership table).
URL
- Service tierhttps://auth.mattering.io/api/internal/organizations/{org_id}/workspaces/
Path parameters
Query parameters
| Name | Default |
email | none |
user_id | none |
Responses
200 bare JSON object (no envelope)
{
"workspaces": [
"..."
]
}
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/internal/organizations/ORG_ID/workspaces/?email=...&user_id=..." \
-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_workspace_views.py (internal_workspace_views.list_org_workspaces)