Menu
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

StatusCode
401invalid_token
401missing_bearer
404user_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

NameDefault
active_onlynone

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)

KeyRequiredDefault
default_workspace_nameoptional or conditionalnone
nameoptional 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

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

StatusCode
400Organization name is required message
400Organization name must be 100 characters or less message
400Workspace 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

NameType
org_iduuid

Body keys (JSON)

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

{
  "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

StatusCode
400Organization name does not match. Deletion cancelled. message
403Only organization owners can delete an organization message
404Organization 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

NameType
org_iduuid

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

NameType
org_iduuid

Query parameters

NameDefault
emailnone
user_idnone

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)

All Auth resources
Start Free Explore our Products