Rename or delete a team

curl --request PUT \
  --url https://web-api.dev.soxai.site/api/orgs/{org_id}/teams \
  --header 'Authorization: Bearer <token>'

const options = {method: 'PUT', headers: {Authorization: 'Bearer <token>'}};

fetch('https://web-api.dev.soxai.site/api/orgs/{org_id}/teams', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "msg": "3 orgUsers updated"
}

{
  "error": "bad-request",
  "error_msg": "old_team_name must not be empty"
}

{
  "error": "http-error",
  "error_msg": "Invalid authentication credentials. <reason>"
}

{
  "error": "forbidden",
  "error_msg": "Not enough permission"
}

{
  "error": "not-found",
  "error_msg": "Org '<org_id>' not found"
}

{
  "error": "unprocessable-entity",
  "error_msg": "body.<field>: <validation message>"
}

{
  "error": "rate-limited",
  "error_msg": "Rate limit exceeded. Retry after <n> seconds."
}

{
  "error": "internal-server-error",
  "error_msg": "Failed to fetch data: <error_message>"
}

Organization Members

Rename or delete a team

Not callable with a Sandbox key

A request authenticated with a Sandbox soxai-api-key is answered 403 This endpoint is not available in the sandbox., because it changes state that every Sandbox caller shares. It is published here because the Sandbox runs the same build; use it in Production. See Sandbox.

Rename a team across every member of an organization that carries it.

A team is not a document of its own: it exists only as a value in each member’s teams list. Renaming therefore rewrites that value on every member, and a rename that matches nobody changes nothing and is reported as a failure rather than as a success.

Parameters

org_id (path, required) - organization identifier.
old_team_name (query, required) - the team name to replace.
new_team_name (query, required) - the replacement name. Send it empty to delete the team, which removes the name from every member that carries it.

Response

200 {"success": true, "msg"} naming how many members were rewritten.

Errors

Status	Condition
400	`old_team_name` is empty
404	The organization does not exist, or no member of it carries `old_team_name`

Authorization

Scheme: Authorization: Bearer <idToken> or soxai-api-key: <api key>.
Accepted roles: PartnerAdmin, OrgAdmin
Admin is accepted regardless of the roles above.
PartnerAdmin reaches only an org owned by its own company; any other caller must carry an orgId claim naming exactly {org_id}.
Denials: a PartnerAdmin naming another company’s org receives 403 PartnerAdmin can change only the org that belongs to your company; a caller whose orgId claim does not name {org_id} receives 403 orgId not match; anyone else receives 403 Not enough permission.

PUT

api

orgs

{org_id}

teams

Rename or delete a team

curl --request PUT \
  --url https://web-api.dev.soxai.site/api/orgs/{org_id}/teams \
  --header 'Authorization: Bearer <token>'

const options = {method: 'PUT', headers: {Authorization: 'Bearer <token>'}};

fetch('https://web-api.dev.soxai.site/api/orgs/{org_id}/teams', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "msg": "3 orgUsers updated"
}

{
  "error": "bad-request",
  "error_msg": "old_team_name must not be empty"
}

{
  "error": "http-error",
  "error_msg": "Invalid authentication credentials. <reason>"
}

{
  "error": "forbidden",
  "error_msg": "Not enough permission"
}

{
  "error": "not-found",
  "error_msg": "Org '<org_id>' not found"
}

{
  "error": "unprocessable-entity",
  "error_msg": "body.<field>: <validation message>"
}

{
  "error": "rate-limited",
  "error_msg": "Rate limit exceeded. Retry after <n> seconds."
}

{
  "error": "internal-server-error",
  "error_msg": "Failed to fetch data: <error_message>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

org_id

string

required

Organization ID.

Example:

"org_123"

Query Parameters

old_team_name

string

required

Existing team name.

Example:

"sales"

new_team_name

string

required

Replacement team name.

Example:

"engineering"

Response

msg names how many members were rewritten.

Get started

API Reference (Sandbox)

API Reference (Production)

About

Rename or delete a team

Authorizations

Path Parameters

Query Parameters

Response