Menu
POST milestones/ Service tier

POST to milestones/. derived from route

URL

  • Service tierhttps://auth.mattering.io/api/internal/milestones/

Body keys (JSON)

KeyRequiredDefault
detailsoptional or conditionalnone
emailoptional or conditionalnone
keyoptional 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)

{
  "recorded": true,
  "advanced": "...",
  "stage": "..."
}

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

Errors

StatusCode
400invalid_json
400key_required
400user_email_required
404user_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

NameDefault
org_idnone

Body keys (JSON)

KeyRequiredDefault
org_idoptional or conditionalnone
timezoneoptional 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)

{
  "org_id": "...",
  "name": "...",
  "timezone": "..."
}

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

Errors

StatusCode
400invalid_timezone
400org_id_required
404organization_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)

KeyRequiredDefault
detected_timezoneoptional or conditionalnone
emailoptional or conditionalnone
org_idoptional or conditionalnone
timezoneoptional or conditionalnone
timezone_autooptional or conditionalnone
user_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)

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

StatusCode
400invalid_timezone
404user_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

NameDefault
public_idnone

Body keys (JSON)

KeyRequiredDefault
public_idoptional or conditionalnone
timezoneoptional 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)

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

StatusCode
400invalid_timezone
400public_id_required
404workspace_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

NameDefault
emailnone
user_idnone

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

NameType
user_idint
org_iduuid

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

StatusCode
404user_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

NameType
user_idint

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

StatusCode
404user_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)

All Auth resources
Start Free Explore our Products