OAuth Client Registration And Connections

These routes manage OAuth client records and related relationship data.

They are public direct API surfaces on api.user.m7.org, even though they typically require authenticated owner or first-party flow context.

Current usage is split across:

  • sso.user.m7.org /register for create-oriented dynamic registration flow
  • user.m7.org app registration and management UI

/oauth

Route What it does Notes
/oauth Family root for OAuth-related management routes. Treat as a route index/controller surface, not the main endpoint for business actions.

/oauth/clients/*

Route What it does Notes
/oauth/clients/insert Creates a new OAuth client record. Current insert flow creates a draft client and assigns a generated client_id.
/oauth/clients/view Returns one OAuth client record. Used by app registration and detail views.
/oauth/clients/search Lists OAuth client records visible to the caller. Management and search helper.
/oauth/clients/update Updates the main client record. General client config update surface. Also accepts optional child-list fields such as ip_whitelist when present.
/oauth/clients/delete Deletes or retires a client record. Used by dynamic registration cleanup and admin flows.
/oauth/clients/recover Restores a previously deleted or archived client. Lifecycle helper.
/oauth/clients/update_status Changes the lifecycle status of a client. Used by registration workflows and publishing-state changes.
/oauth/clients/set_auth Sets token_endpoint_auth_method and related auth config. Important for auth-method changes.
/oauth/clients/set_knobs Updates token TTL and claim-shaping knobs. Advanced app configuration surface.
/oauth/clients/set_config_lock Sets or updates the config-lock gate for future changes. Protects later edits to sensitive config.
/oauth/clients/tenants Returns available tenant context or tenant choices for a client. Tenant-aware app registration helper.
/oauth/clients Controller/index route for the family. Treat as a family root rather than a primary business endpoint.

/oauth/clients/search pagination

/oauth/clients/search now supports the shared pagination request inputs:

  • limit
  • page_number
  • offset
  • cursor

When one or more of those fields is present in the request, the endpoint returns the shared pageable collection shape described in:

That means data becomes an object containing:

  • items
  • limit
  • total_count
  • next_offset
  • page_number
  • page_total
  • next_cursor

Current pageable default for this endpoint:

  • limit = 20 when no limit is supplied

Current rollout note:

  • callers that do not send pagination inputs still receive the legacy flat list in data
  • callers that do send pagination inputs receive the pageable data object

This compatibility mode is temporary and exists to avoid breaking existing first-party callers during the app-registration migration.

/oauth/clients/connections/*

These routes manage connection records between OAuth clients and external or provider-style resources.

Route What it does Notes
/oauth/clients/connections/search Lists connection records. Management and search helper.
/oauth/clients/connections/insert Creates a new connection record. First-party admin helper.
/oauth/clients/connections/view Returns one connection record. Detail view helper.
/oauth/clients/connections/update Updates one connection record. Admin and config helper.
/oauth/clients/connections/delete Deletes or retires a connection record. Lifecycle helper.
/oauth/clients/connections/recover Restores a deleted or archived connection. Lifecycle helper.
/oauth/clients/connections/update_status Changes connection status. Publish, disable, or helper-state changes.
/oauth/clients/connections/verify Verifies a connection configuration. Connectivity and config validation helper.
/oauth/clients/connections Controller/index route for the subtree. Family root.

/oauth/clients/connected/*

These routes represent connected-client relationship views.

Route What it does Notes
/oauth/clients/connected/search Lists connected relationships. Relationship search helper. Supports limit, page_number, offset, and cursor.
/oauth/clients/connected/insert Creates a connected relationship. Admin helper.
/oauth/clients/connected/view Returns one connected relationship. Detail helper.
/oauth/clients/connected/update Updates one connected relationship. Admin helper.
/oauth/clients/connected Controller/index route for the subtree. Family root.

/oauth/clients/connected/search pagination

/oauth/clients/connected/search supports these pagination inputs:

  • limit
  • page_number
  • offset
  • cursor

If one or more of those fields is included in the request, the endpoint returns a pageable data object with:

  • items
  • limit
  • total_count
  • next_offset
  • page_number
  • page_total
  • next_cursor

Current pageable default for this endpoint:

  • limit = 20 when no limit is supplied

If no pagination inputs are included, the endpoint currently continues to return the legacy flat list in data for backward compatibility with older first-party callers.

/oauth/clients/authorized/*

These routes represent authorization or approval records tied to OAuth clients.

Route What it does Notes
/oauth/clients/authorized/search Lists authorized records. Relationship search helper. Supports limit, page_number, offset, and cursor.
/oauth/clients/authorized/view Returns one authorized record. Detail helper.
/oauth/clients/authorized/update Updates an authorized record. Admin and helper state changes.
/oauth/clients/authorized/update_status Changes authorized-record status. Lifecycle helper.
/oauth/clients/authorized Controller/index route for the subtree. Family root.

/oauth/clients/authorized/search pagination

/oauth/clients/authorized/search supports these pagination inputs:

  • limit
  • page_number
  • offset
  • cursor

If one or more of those fields is included in the request, the endpoint returns a pageable data object with:

  • items
  • limit
  • total_count
  • next_offset
  • page_number
  • page_total
  • next_cursor

Current pageable default for this endpoint:

  • limit = 20 when no limit is supplied

If no pagination inputs are included, the endpoint currently continues to return the legacy flat list in data for backward compatibility with older first-party callers.

Caller Guidance

  • use these routes for app registration and app-management workflows
  • the most important registration bootstrap routes are currently:
    • /oauth/clients/insert
    • /oauth/clients/set_auth
    • /oauth/clients/update_status
    • /oauth/clients/delete
  • sso.user.m7.org /register currently depends on that create, set-auth, update-status, and delete subset
1