Common Conventions

Base URL

All routes in this doc set are relative to:

https://api.user.m7.org/api/v2

Example:

  • route: /auth/user/root-session
  • full URL: https://api.user.m7.org/api/v2/auth/user/root-session

Support Boundary

This doc set uses two endpoint buckets.

Public

Public routes are part of the supported direct contract on api.user.m7.org.

That still does not imply anonymous access.

Many public routes require:

  • a signed-in user
  • an authenticated org-owner context
  • an authenticated app-owner context

Private

Private routes are live on the host, but they are not meant to be integrated against directly.

These are typically:

  • first-party SSO bridge routes
  • relay-backed token issue or token exchange helpers
  • retained legacy handlers

The main private family today is the auth bridge collection under:

  • /auth/user/*
  • /auth/member/*
  • /auth/signup
  • /oauth/client_credentials/issue

Current Request Style

Current first-party consumers typically send JSON request bodies, even for routes whose names look CRUD-like.

Practical guidance:

  • use POST with JSON unless a stricter contract already exists in your caller
  • keep using the request shape already proven in the calling app when integrating with an existing flow
  • do not assume these endpoints are clean REST resources just because the names look resource-oriented

Authentication Patterns

There are three broad patterns in the current codebase.

1. Credential-to-token endpoints

These accept credentials directly and mint session or token material.

Examples:

  • /auth/user/root-session
  • /auth/user/login
  • /auth/member/root-session
  • /auth/member/login

These commonly use fields like:

  • auth.user
  • auth.pass
  • auth.code
  • auth.org
  • fingerprint
  • dpop
  • htu
  • relay.id
  • relay.key

2. Token exchange endpoints

These accept an existing token or session artifact and return a new token package.

Examples:

  • /auth/user/exchange
  • /auth/member/exchange
  • /oauth/device/pickup
  • /oauth/device/refresh/bundle

These commonly use fields like:

  • auth.token or token
  • auth.method
  • binding_chain
  • binding_link
  • fingerprint
  • dpop
  • htu

3. Authenticated resource or management endpoints

These use the shared auth layer and operate on the authenticated principal.

Examples:

  • /account/me/get
  • /org/search
  • /org/client/search
  • /oauth/clients/insert
  • /account/preferences/get

In the current code, most of these routes validate credentials by default unless the endpoint explicitly disables that behavior.

Response Shape

Responses are JSON, but the exact envelope is not perfectly uniform across the full surface.

Common patterns include:

  • status
  • comment
  • data
  • endpoint-specific payload objects

Practical guidance:

  • expect JSON
  • inspect status or equivalent success markers
  • do not assume every endpoint returns the exact same wrapper

List Pagination

List and search endpoints that support pager UIs should follow the shared pagination contract documented in:

That contract standardizes:

  • request inputs like limit, page_number, offset, and cursor
  • response fields like items, total_count, page_total, and next_cursor

Typical Callers

First-party SSO bridge callers

Examples:

  • sso.user.m7.org /process-login
  • sso.user.m7.org /process-signup
  • sso.user.m7.org /token
  • shared SSO client-credentials grant helpers

These mostly use the private docs under:

First-party user or owner tools

Examples:

  • user.m7.org
  • owner-facing app registration tools
  • owner-facing offline-access management tools

These mostly use the public docs under:

Retained Legacy Auth Endpoints

A small auth/member-auth set is intentionally retained on disk under legacy directories so earlier iterations remain available without looking like the primary live flow.

See:

1