Organization management

Manage organizations, their built-in Management group, ordinary groups, and organization-scoped member records. All routes use a bearer token with access to the selected organization. An organization member record is called a member in this guide even though its route path is /org/client/*.

Authentication

A human caller uses a consumer-user access token and must have active access in the organization's Management group. An organization-member access token does not, by itself, authorize these management routes.

Organization application tokens are accepted for their assigned organization when the application has active Management-group access and the organization still has an active human management user. An organization application cannot create an organization. See the authorization guide for the complete human- and machine-principal rules.

Organization routes

Route	Required fields	Optional fields and behavior
`/org/search`	None	`archived` boolean. Returns organizations the caller can manage, not only organizations the caller created.
`/org/insert`	`name`	`slug`, `description`, `data`, `status`, `expires`. A blank `slug` is generated. The owner is always the token principal; machine applications cannot create organizations.
`/org/get`	`id`	Returns the organization with its `config` and `knobs`.
`/org/update`	`id`	Partial update of the standard organization fields. Does not modify policy knobs.
`/org/set_knobs`	`id`	Send only policy fields to change. `null` or `""` clears an optional override.
`/org/delete`	`id`	Archives or deletes the organization.
`/org/restore`	`id`	Restores a previously archived organization.
`/org/identity/get`	`org`	`oid` is an alias; `vendor` defaults to `m7`. An organization with no identity returns `rid: null` and `active: false`.
`/org/identity/set`	`org`	`vendor` defaults to `m7`; use `active` to set state. Creating or recreating a missing child also requires `pass` and `confirm`.

Create an organization

curl -sS https://api.user.m7.org/api/v2/org/insert \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example Org",
    "slug": "example-org",
    "description": "Example organization"
  }'

{
  "status": 1,
  "comment": "INSERT",
  "data": {
    "id": "ORG_UUID",
    "name": "Example Org",
    "slug": "example-org",
    "status": "active"
  }
}

Organization policy knobs

/org/set_knobs is the policy endpoint. Send id plus only the fields to change. The response comment is SET_KNOBS and the response includes the resolved config and knobs maps.

Token policy fields

Each token family supports a default TTL, lower and upper bound, mutability flag, default claim object, and claim mutability flag:

access_token_ttl_default          access_token_ttl_min
access_token_ttl_max              access_token_ttl_mutable
access_token_claims               access_token_claims_mutable
refresh_token_ttl_default         refresh_token_ttl_min
refresh_token_ttl_max             refresh_token_ttl_mutable
refresh_token_claims              refresh_token_claims_mutable
client_credentials_token_ttl_default  client_credentials_token_ttl_min
client_credentials_token_ttl_max      client_credentials_token_ttl_mutable
client_credentials_claims             client_credentials_claims_mutable

TTL values are positive integer seconds.
*_mutable values are booleans.
*_claims values are JSON objects (an object or a JSON-encoded object).
Send null or "" to remove an optional value.

Application-policy fields

Organization policy fields use the tenant_policy_* prefix. The accepted names cover public registration, federated sign-in, hosted registration, and hosted branding:

tenant_policy_allow_public_registrations
tenant_policy_allow_federated_signin
tenant_policy_hosted_allow_public_registrations
tenant_policy_hosted_registration_email_requirement
tenant_policy_hosted_registration_display_name_requirement
tenant_policy_hosted_registration_email_verification
tenant_policy_hosted_registration_phone_requirement
tenant_policy_hosted_registration_phone_verification
tenant_policy_hosted_registration_password_requirement
tenant_policy_hosted_registration_first_name_requirement
tenant_policy_hosted_registration_last_name_requirement
tenant_policy_hosted_registration_username_requirement
tenant_policy_hosted_registration_include_tenant_terms_in_consent
tenant_policy_hosted_registration_human_verification_requirement
tenant_policy_hosted_registration_activation_mode
tenant_policy_hosted_registration_activation_rule
tenant_policy_hosted_registration_activation_methods
tenant_policy_hosted_registration_send_welcome_email
tenant_policy_hosted_branding_display_name
tenant_policy_hosted_branding_hero_logo_url
tenant_policy_hosted_branding_compact_logo_url
tenant_policy_hosted_branding_home_url
tenant_policy_hosted_header_hero_show_logo
tenant_policy_hosted_header_hero_show_name
tenant_policy_hosted_header_compact_show_logo
tenant_policy_hosted_header_compact_show_name
tenant_policy_hosted_branding_color_primary
tenant_policy_hosted_branding_color_background
tenant_policy_hosted_branding_color_surface
tenant_policy_hosted_branding_support_url
tenant_policy_hosted_branding_terms_url
tenant_policy_hosted_branding_privacy_url

Boolean policy fields accept JSON booleans. URL values require absolute HTTPS URLs where applicable, colors use CSS hex values, and tenant_policy_hosted_registration_activation_methods accepts email, phone, or email,phone and is returned as an array.

Set a token-policy default

curl -sS https://api.user.m7.org/api/v2/org/set_knobs \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "ORG_UUID",
    "access_token_ttl_default": 900
  }'

Management group

/org/manage/* manages the built-in Management group. It is distinct from ordinary organization groups. Every request must use only the fields shown below; other fields are rejected.

Route	Required fields	Optional fields and behavior
`/org/manage/search`	`org`	`role` plus shared pagination fields.
`/org/manage/get`	`org`, `principal`	Returns one Management membership.
`/org/manage/add`	`org`, `principal`, `type`, `role`	`type` is `user`, `app`, or `delegate`.
`/org/manage/set`	`org`, `principal`, `role`	Replaces the stored role label.
`/org/manage/remove`	`org`, `principal`	Removes a membership only when an owner remains.

Allowed role values are owner, admin, member, and viewer. They are stored labels; all current Management-group members have the same effective management access. At least one owner must remain when a membership is changed or removed.

For type: "user", principal is the user UUID. For type: "app", it is the OAuth application's public client_id. A delegate principal must already exist.

Add a Management member

curl -sS https://api.user.m7.org/api/v2/org/manage/add \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "org": "ORG_UUID",
    "type": "user",
    "principal": "USER_UUID",
    "role": "admin"
  }'

{
  "status": 1,
  "comment": "OK",
  "data": {
    "access": {
      "id": "MANAGEMENT_MEMBERSHIP_UUID",
      "principal": "MANAGEMENT_PRINCIPAL_UUID",
      "role": "admin"
    },
    "principal": {
      "rid": "USER_UUID",
      "name": "alice",
      "type": "user"
    }
  }
}

Organization groups

Use /org/group/* for ordinary groups such as Operators or Billing.

Route	Required fields	Notes
`/org/group/search`	`org`	Optional `archived` boolean.
`/org/group/insert`	`org`, `name`	Creates a group.
`/org/group/get`	`id`	Looks up a group by record ID. `org` is not used as a lookup key.
`/org/group/update`	`org`, `id`	Partially updates a group.
`/org/group/delete`	`org`, `id`	Archives or deletes a group.
`/org/group/restore`	`org`, `id`	Restores a group.

curl -sS https://api.user.m7.org/api/v2/org/group/insert \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "org": "ORG_UUID",
    "name": "Operators"
  }'

Organization members

The /org/client/* path manages organization members. The client in the path is a member record, not an OAuth application.

Route	Required fields	Optional fields and behavior
`/org/client/search`	`org`	`archived`, search fields, and optional `group` (group UUID or slug) to filter membership.
`/org/client/insert`	`org`, `name`	`user` may link an active, unarchived consumer-user UUID. An unavailable user returns `linked user is unavailable`.
`/org/client/get`	`org`, plus `id` or `name`	Returns one member.
`/org/client/update`	`org`, `id`	Partial update; `user` uses the same availability check.
`/org/client/delete`	`org`, `id`	Archives or deletes a member.
`/org/client/restore`	`org`, `id`	Restores a member.
`/org/client/password`	`org`, `id`, `pass`, `confirm`	Cannot change the password for a member linked to a consumer user.
`/org/client/federated-identity`	`org`, `id`, `vendor`, `rid`	`handle` is optional. Binds a federated identity to the organization member.

Create an organization member

curl -sS https://api.user.m7.org/api/v2/org/client/insert \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "org": "ORG_UUID",
    "name": "alice"
  }'

The create response returns comment: "OK" and the new member record in data.

Member group membership

Use /org/client/group/* to manage the relationship between an organization member and an ordinary group.

Route	Required fields	Notes
`/org/client/group/add`	`org`, `id`, `group`	`id` is the member ID; `group` is the group ID. The membership role is always `member`. Duplicate addition returns `client is already a member of this group`.
`/org/client/group/remove`	`org`, `id`, `group`	Removes a member from a group.
`/org/client/group/get`	`org`, `group`, plus `id` or `name`	Looks up a relationship by group and member.
`/org/client/group/set`	`org`, `group`, plus `client` or `id`	Updates the existing relationship. `id` is an alias for the member ID when `client` is omitted.
`/org/client/group/search`	`org`, plus group `id` or `name`	Lists members in one group.
`/org/client/group/all`	`org`, `id`	Returns all organization groups with membership information for one member.

Add a member to a group

curl -sS https://api.user.m7.org/api/v2/org/client/group/add \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "org": "ORG_UUID",
    "id": "MEMBER_UUID",
    "group": "GROUP_UUID"
  }'

{
  "status": 1,
  "comment": "ADDED",
  "data": {
    "group": "GROUP_UUID",
    "client": "MEMBER_UUID",
    "role": "member"
  }
}