Team

Base URL: $BUSINESS_API

The object

idstring · optional
device_namestring · optional

Parsed label such as "Chrome 128 on macOS" or "Mobile app on Android"

user_agentstring · optional
ip_addressstring · optional
last_active_atstring (date-time) · optional
created_atstring (date-time) · optional
expires_atstring (date-time) · optional
is_currentboolean · optional
The object
{
  "id": "ses_2c2ff4Evh00LjE4JZcmdbIifJSI",
  "device_name": "Ana Matsinhe",
  "user_agent": "user agent",
  "ip_address": "Av. Julius Nyerere 1420, Maputo",
  "last_active_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "expires_at": "2026-11-19T09:30:00Z",
  "is_current": true
}

List a team member sessions

Logs

GET /team/members/{id}/sessions

Returns, in a data array, the live sessions the member holds in the caller's team, with device name, user agent, IP address, last activity, creation and expiry times. is_current marks the caller's own session. Returns 404 when the member is not active in this team; requires the team read permission.

Parameters

idstring · path · required

Membership ID of the team member, as returned by the members list.

Returns

200 List a team member sessions

Show attributes
dataarray of Session · optional
Show child attributes
idstring · optional
device_namestring · optional

Parsed label such as "Chrome 128 on macOS" or "Mobile app on Android"

user_agentstring · optional
ip_addressstring · optional
last_active_atstring (date-time) · optional
created_atstring (date-time) · optional
expires_atstring (date-time) · optional
is_currentboolean · optional

Errors 400 · 401

Permissions business:team:read · Roles: admin, owner

curl -X GET "$BUSINESS_API/team/members/{id}/sessions" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "ses_2c2ff4Evh00LjE4JZcmdbIifJSI",
      "device_name": "Ana Matsinhe",
      "user_agent": "user agent",
      "ip_address": "Av. Julius Nyerere 1420, Maputo",
      "last_active_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z",
      "expires_at": "2026-11-19T09:30:00Z",
      "is_current": true
    }
  ]
}

End every session of a team member

Logs

DELETE /team/members/{id}/sessions

Ends every device session the member holds in the caller's team, forcing a new sign-in, and returns the number ended as revoked. Only an owner may end an owner's sessions (403); an unknown member returns 404. Requires the team manage permission and is recorded in the audit trail.

Parameters

idstring · path · required

Membership ID of the team member whose sessions are ended.

Returns

200 End every session of a team member

Show attributes
revokedinteger · optional

Errors 400 · 401

Permissions business:team:manage · Roles: admin, owner

curl -X DELETE "$BUSINESS_API/team/members/{id}/sessions" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "revoked": 1
}

List invitations for the active utility or organization team

Logs

GET /team/invitations

Returns invitations of the caller's current team (the utility tenant, or the organization when signed in as organization staff) in cursor pages using limit and after. Only pending invitations are returned unless a status query parameter asks for another; pending invitations past their expiry are reported as expired. Requires the team read permission of that context.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Invitations scoped to the authenticated utility or organization

Show attributes
dataarray of TeamInvitation · required
Show child attributes
idstring · required
emailstring · optional
phonestring · optional
full_namestring · optional
rolesarray of string · required
statusstring · required

one of pending, accepted, revoked, expired

expires_atstring (date-time) · required
created_atstring (date-time) · required
dev_codestring · optional

Invitation token echoed only in development mode

has_moreboolean · required
next_cursorstring · optional

Errors 400 · 401

Permissions business:team:read · Roles: admin, owner

curl -X GET "$BUSINESS_API/team/invitations" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "tea_29hCWbtKGjr0MddW6tj00zL8mXp",
      "email": "ana.matsinhe@example.org",
      "phone": "+258841234567",
      "full_name": "Ana Matsinhe",
      "roles": [
        "role"
      ],
      "status": "pending",
      "expires_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z",
      "dev_code": "DEV-2026-000142"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Invite a member to the active utility or organization team

Logs

POST /team/invitations

Sends a one-time invitation token by e-mail, or by text message when only phone is given, offering the listed roles in the caller's current team; the invitation expires after 7 days and replaces any earlier pending invitation for the same recipient. Only an owner can grant the owner role (403), an unknown role or missing e-mail and phone returns 400, someone who is already an active member returns 409, and 503 means the message could not be delivered, in which case the invitation is revoked. Requires the team manage permission and is recorded in the audit trail.

Body application/json

emailstring · optional

Required when phone is absent

phonestring · optional

Required when email is absent

full_namestring · optional
rolesarray of string · required

Returns

201 Invitation for the authenticated utility or organization team

Show attributes
idstring · required
emailstring · optional
phonestring · optional
full_namestring · optional
rolesarray of string · required
statusstring · required

one of pending, accepted, revoked, expired

expires_atstring (date-time) · required
created_atstring (date-time) · required
dev_codestring · optional

Invitation token echoed only in development mode

Errors 400 · 401 · 503

Permissions business:team:manage · Roles: admin, owner

curl -X POST "$BUSINESS_API/team/invitations" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ana.matsinhe@example.org",
  "phone": "+258841234567",
  "full_name": "Ana Matsinhe",
  "roles": [
    "role"
  ]
}'
Response 201
{
  "id": "tea_29hCWbtKGjr0MddW6tj00zL8mXp",
  "email": "ana.matsinhe@example.org",
  "phone": "+258841234567",
  "full_name": "Ana Matsinhe",
  "roles": [
    "role"
  ],
  "status": "pending",
  "expires_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "dev_code": "DEV-2026-000142"
}

Revoke utility team invitation

Logs

DELETE /team/invitations/{id}

Revoke a pending invitation from the active utility or organization team

Marks a pending invitation of the caller's team as revoked so its token can no longer be used, and answers 204. Returns 404 when the invitation is not in this team and 409 when it is no longer pending; requires the team manage permission and is recorded in the audit trail.

Returns

204 Revoke a pending invitation scoped to the authenticated context

Errors 400 · 401

Permissions business:team:manage · Roles: admin, owner

curl -X DELETE "$BUSINESS_API/team/invitations/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 204

Revoke a pending invitation scoped to the authenticated context

List members of the active utility or organization team

Logs

GET /team/members

Returns the active members of the caller's current team (the utility tenant or the organization) with their user details, roles, status and join date, in cursor pages using limit and after. Requires the team read permission of that context.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Members scoped to the authenticated utility or organization

Show attributes
dataarray of TeamMember · required
Show child attributes
idstring · required
userobject · required
Show child attributes
idstring · required
emailstring · optional
phonestring · optional
full_namestring · required
localestring · required

one of pt-MZ, en-US

statusstring · required

one of active, disabled

email_verifiedboolean · required
phone_verifiedboolean · required
created_atstring (date-time) · required
rolesarray of string · required
statusstring · required
joined_atstring (date-time) · required
has_moreboolean · required
next_cursorstring · optional

Errors 400 · 401

Permissions business:team:read · Roles: admin, owner

curl -X GET "$BUSINESS_API/team/members" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "tea_2CG53ca1REQBv6SPVO6TpaYfp4u",
      "user": {
        "id": "use_2ZtKedjGsDLWMRDGSD9S0vnswD5",
        "email": "ana.matsinhe@example.org",
        "phone": "+258841234567",
        "full_name": "Ana Matsinhe",
        "locale": "pt-MZ",
        "status": "active",
        "email_verified": true,
        "phone_verified": true,
        "created_at": "2026-11-19T09:30:00Z"
      },
      "roles": [
        "role"
      ],
      "status": "active",
      "joined_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Remove a member from the active utility or organization team

Logs

DELETE /team/members/{id}

Remove a member from the active utility or organization team (the last owner cannot be removed)

Ends the member's membership in the caller's team, signs out every session tied to it, and answers 204. Only an owner may remove another owner (403), removing the last owner returns 409, and an unknown or inactive member returns 404. Requires the team manage permission and is recorded in the audit trail.

Returns

204 Remove a member scoped to the authenticated context

Errors 400 · 401

Permissions business:team:manage · Roles: admin, owner

curl -X DELETE "$BUSINESS_API/team/members/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 204

Remove a member scoped to the authenticated context

Update utility team member roles

Logs

PATCH /team/members/{id}/roles

Replace a member's roles in the active utility or organization team

Replaces the member's roles with the roles array and returns the updated member. The member's existing sessions are revoked so the new permissions take effect at the next sign-in. Only an owner may grant the owner role or demote an owner (403), demoting the last owner returns 409, and an unknown role returns 400; requires the team manage permission.

Body application/json

rolesarray of string · required

Returns

200 Replace member roles scoped to the authenticated context; the last owner cannot be demoted

Show attributes
idstring · required
userobject · required
Show child attributes
idstring · required
emailstring · optional
phonestring · optional
full_namestring · required
localestring · required

one of pt-MZ, en-US

statusstring · required

one of active, disabled

email_verifiedboolean · required
phone_verifiedboolean · required
created_atstring (date-time) · required
rolesarray of string · required
statusstring · required
joined_atstring (date-time) · required

Errors 400 · 401

Permissions business:team:manage · Roles: admin, owner

curl -X PATCH "$BUSINESS_API/team/members/{id}/roles" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "roles": [
    "role"
  ]
}'
Response 200
{
  "id": "tea_2CG53ca1REQBv6SPVO6TpaYfp4u",
  "user": {
    "id": "use_2ZtKedjGsDLWMRDGSD9S0vnswD5",
    "email": "ana.matsinhe@example.org",
    "phone": "+258841234567",
    "full_name": "Ana Matsinhe",
    "locale": "pt-MZ",
    "status": "active",
    "email_verified": true,
    "phone_verified": true,
    "created_at": "2026-11-19T09:30:00Z"
  },
  "roles": [
    "role"
  ],
  "status": "active",
  "joined_at": "2026-11-19T09:30:00Z"
}

List the built-in roles of the utility context

Logs

GET /team/roles

Returns, in a data array, the role definitions that can be assigned in the caller's current team context, the same list used to validate invitations and role changes. Requires the team read permission.

Returns

200 List the built-in roles of the utility context

Show attributes
dataarray of RoleDefinition · required
Show child attributes
namestring · required
contextstring · required

one of platform, tenant, consumer

descriptionstring · required
scopesarray of string · required

Errors 400 · 401

Permissions business:team:read · Roles: admin, owner

curl -X GET "$BUSINESS_API/team/roles" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "name": "Ana Matsinhe",
      "context": "platform",
      "description": "Leitura confirmada no local.",
      "scopes": [
        "scope"
      ]
    }
  ]
}