POST
milestones/
Service tier
POST to milestones/. derived from route
URL
- Service tierhttps://auth.mattering.io/api/internal/milestones/
Body keys (JSON)
| Key | Required | Default |
details | optional or conditional | none |
email | optional or conditional | none |
key | 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)
{
"recorded": true,
"advanced": "...",
"stage": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | invalid_json |
| 400 | key_required |
| 400 | user_email_required |
| 404 | user_not_found |
Example
curl -X POST "https://auth.mattering.io/api/internal/milestones/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-H "Content-Type: application/json" \
-d '{
"details": "...",
"email": "...",
"key": "..."
}'
Source: mattering_auth/internal_milestone_views.py (internal_milestone_views.report_milestone)
GET
timezone/options/
Service tier
GET /api/internal/timezone/options/ returns grouped picker list.
Lets every app's settings UI render the same curated zone list without each one hardcoding its own (Sales, QR and Contracts each grew a different hand-rolled list before this existed).
URL
- Service tierhttps://auth.mattering.io/api/internal/timezone/options/
Responses
200 bare JSON object (no envelope)
{
"groups": [
{
"label": "...",
"zones": [
{
"value": "...",
"label": "..."
}
]
}
],
"default": "..."
}
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/timezone/options/" \
-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_timezone_views.py (internal_timezone_views.timezone_options)
GETPOST
timezone/organization/
Service tier
GET/POST /api/internal/timezone/organization/
GET ?org_id= returns {org_id, name, timezone} POST {org_id, timezone} returns same, after validation.
This is the org business calendar: the EXECUTION fallback for schedules, rollups and date-only fields platform-wide. It can never be blank.
URL
- Service tierhttps://auth.mattering.io/api/internal/timezone/organization/
Query parameters
Body keys (JSON)
| Key | Required | Default |
org_id | optional or conditional | none |
timezone | 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)
{
"org_id": "...",
"name": "...",
"timezone": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | invalid_timezone |
| 400 | org_id_required |
| 404 | organization_not_found |
Example
curl -X POST "https://auth.mattering.io/api/internal/timezone/organization/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-H "Content-Type: application/json" \
-d '{
"org_id": "...",
"timezone": "..."
}'
Source: mattering_auth/internal_timezone_views.py (internal_timezone_views.organization_timezone)
GETPOST
timezone/user/
Service tier
GET/POST /api/internal/timezone/user/
GET ?email= | ?user_id= [&org_id=] returns the payload above. POST {email|user_id, org_id?, timezone?, timezone_auto?, detected_timezone?}
POST semantics, all fields optional and independently applied:
* timezone: '' clears the pin (back to auto), otherwise must be a
valid IANA key. Setting a non-empty pin also flips timezone_auto
off, because "pinned" and "follow the browser" are contradictory and
callers forget to send both.
* timezone_auto: explicit override of that inference.
* detected_timezone: what the browser reported. Written even when a
pin is active so that clearing the pin lands somewhere sensible.
URL
- Service tierhttps://auth.mattering.io/api/internal/timezone/user/
Body keys (JSON)
| Key | Required | Default |
detected_timezone | optional or conditional | none |
email | optional or conditional | none |
org_id | optional or conditional | none |
timezone | optional or conditional | none |
timezone_auto | optional or conditional | none |
user_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)
{
"user_id": "...",
"email": "...",
"timezone": "...",
"timezone_auto": "...",
"detected_timezone": "...",
"organization_timezone": "...",
"display_timezone": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | invalid_timezone |
| 404 | user_not_found |
Example
curl -X POST "https://auth.mattering.io/api/internal/timezone/user/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-H "Content-Type: application/json" \
-d '{
"detected_timezone": "...",
"email": "...",
"org_id": "...",
"timezone": "...",
"timezone_auto": "...",
"user_id": "..."
}'
Source: mattering_auth/internal_timezone_views.py (internal_timezone_views.user_timezone)
GETPOST
timezone/workspace/
Service tier
GET/POST /api/internal/timezone/workspace/
GET ?public_id= returns {public_id, timezone, effective_timezone, ...} POST {public_id, timezone} returns same. '' clears the override (inherit org).
timezone is the raw override and effective_timezone is what schedulers must actually use.
URL
- Service tierhttps://auth.mattering.io/api/internal/timezone/workspace/
Query parameters
| Name | Default |
public_id | none |
Body keys (JSON)
| Key | Required | Default |
public_id | optional or conditional | none |
timezone | 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)
{
"public_id": "...",
"organization_id": "...",
"timezone": "...",
"organization_timezone": "...",
"effective_timezone": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | invalid_timezone |
| 400 | public_id_required |
| 404 | workspace_not_found |
Example
curl -X POST "https://auth.mattering.io/api/internal/timezone/workspace/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-H "Content-Type: application/json" \
-d '{
"public_id": "...",
"timezone": "..."
}'
Source: mattering_auth/internal_timezone_views.py (internal_timezone_views.workspace_timezone)
GET
users/workspaces/
Service tier
GET /api/internal/users/workspaces/?user_id=&email=
All active workspaces the user is an active member of, across every org, each annotated with the user's role. Thin-mirror apps use this for "which spaces can this user access" without local membership tables.
URL
- Service tierhttps://auth.mattering.io/api/internal/users/workspaces/
Query parameters
| Name | Default |
email | none |
user_id | none |
Responses
200 bare JSON object (no envelope)
{
"workspaces": [
"..."
],
"user_id": "..."
}
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/users/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_user_workspaces)
GET
users/{user_id}/orgs/{org_id}/membership/
Service tier
Answer: is ``user_id`` an active member of ``org_id``?
URL: /api/internal/users/<int:user_id>/orgs/<uuid:org_id>/membership/
Response shape (status returns body):
* 200 + ``{"is_member": true, "role": "<role>",
"joined_at": "<iso>", "user_id": <int>,
"org_id": "<uuid>"}``
Active membership exists.* 200 + ``{"is_member": false, "user_id": <int>,
"org_id": "<uuid>"}``
User exists but is not an active member of the org. This
covers (a) no Membership row, (b) Membership row with
is_active=False, and (c) the org doesn't exist (which is
equivalent to "not a member" from the caller's perspective :
no point in returning 404 there since the user is real).* 404 + ``{"error": "user_not_found", "user_id": <int>,
"org_id": "<uuid>"}``
The User PK doesn't exist. Callers (see
org_membership.is_user_in_org) treat this as
is_member=false; we keep the 404 distinct so admins can
spot bad inputs in access logs.The Organization lookup is intentionally cheap: we don't load the full row when answering is_member=false. The query plan is:
* 1 query: SELECT 1 FROM auth_user WHERE id = %s (existence)
* 1 query: ``SELECT role, joined_at FROM auth_membership WHERE
user_id = %s AND organization_id = %s
AND is_active = TRUE``
No N+1, no joins. Suitable for being called once per grant write.
URL
- Service tierhttps://auth.mattering.io/api/internal/users/{user_id}/orgs/{org_id}/membership/
Path parameters
| Name | Type |
user_id | int |
org_id | uuid |
Responses
200 bare JSON object (no envelope)
{
"is_member": true,
"role": "...",
"joined_at": "2026-01-01T00:00:00Z",
"user_id": "...",
"org_id": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 404 | user_not_found |
Example
curl -X GET "https://auth.mattering.io/api/internal/users/USER_ID/orgs/ORG_ID/membership/" \
-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_views.py (internal_views.org_membership_check)
POST
users/{user_id}/revoke-mcp-tokens/
Service tier
Revoke all MCP-audience OAuth tokens for a specific user.
URL: POST /api/internal/users/<int:user_id>/revoke-mcp-tokens/
Forces the MCP client (Cursor, etc.) to re-authorize through the full OAuth flow on its next refresh attempt, picking up fresh identity.
Response: * 200 + {"revoked_access": N, "revoked_refresh": N, "user_id": <int>} * 404 + {"error": "user_not_found"}
URL
- Service tierhttps://auth.mattering.io/api/internal/users/{user_id}/revoke-mcp-tokens/
Path parameters
Responses
200 bare JSON object (no envelope)
{
"revoked_access": 0,
"revoked_refresh": 0,
"user_id": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 404 | user_not_found |
Example
curl -X POST "https://auth.mattering.io/api/internal/users/USER_ID/revoke-mcp-tokens/" \
-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_views.py (internal_views.revoke_user_mcp_tokens)