Docs
Contents

Teams

Overview and use cases

Team and member management within a project: organize users into Teams and use Role.team(teamId[, role]) for batch grants in row / file permissions. Use cases: collaboration spaces (boards, shared documents), team-granularity data sharing, and layered member roles (such as owner / member).

Note the distinction: the in-project Team (this page) versus the management-plane organization (Organization = Team in the Console context, see organization.md). Their APIs share the same shape but have different scopes — organizations manage projects and member billing, while in-project teams only serve authorization within that project.

Prerequisites

Usage workflow

  1. Create team: teams.create({ teamId, name, roles }) (roles optional) — the creator automatically becomes a member and holds the role in roles (including owner); ID.unique() or a custom ID.

  2. Query / maintain: teams.list() (current user's teams), teams.get(teamId), teams.update(teamId, name) (name optional) (including prefs maintenance: getTeamPrefs / updateTeamPrefs), teams.delete(teamId) (requires owner).

  3. Invite member: teams.createMembership({ teamId, roles, email , userId, phone, url, name }) (email, userId, phone, url, name all optional) — at least one of email / userId / phone; url is the redirect address for accepting the invitation; the new member must confirm (confirm) before membership fully takes effect.

  4. Member management: listMemberships(teamId, queries) (queries optional), getMembership, updateMembership({ teamId, membershipId, roles }) to adjust roles, updateMembershipStatus (handles invitation acceptance / join status), deleteMembership to remove.

  5. Using for authorization: use Permission.read(Role.team(teamId)) (optionally with member role Role.team(teamId, 'owner')) in row / file permissions; Client SDK can only grant to teams it has already joined (see permissions.md).

Key parameters and returns

CallKey parametersReturns
createteamId, name, roles (optional; creator role)Models.Team ($id, name, total)
createMembershipteamId, roles[], email (optional)/userId (optional)/phone (optional), url (optional), name (optional)Models.Membership (confirm status, roles)
updateMembershipteamId、membershipId、roles[]Membership
updateMembershipStatusteamId, membershipId, userId, secretMembership (the email invitation link carries credentials)
listMembershipsteamId, queries (optional)MembershipList

Errors and boundaries

SDK Category Differences

Examples by language

The following provides examples by language, item by item along the usage workflow; each card can switch languages (synced across the page).

Create team

import { Client, Teams, ID } from 'agentbase-node-sdk';

const teams = new Teams(client);   // For client initialization, see server-sdk/nodejs.md

const team = await teams.create({ teamId: ID.unique(), name: 'backend', roles: ['owner'] });
// roles is the creator's role, default ["owner"]; teamId is custom or ID.unique()

Query / maintain

Server SDK lists all teams in the project from the administrator view; Web (user Session) only sees the teams the user belongs to.

await teams.list();                                        // All teams in the project, supports queries / search
const team = await teams.get('backend-team');

await teams.updateName('backend-team', 'backend-core');    // Team ID is immutable; only renaming is allowed

await teams.getPrefs('backend-team');                      // Team preferences (free-form key-value JSON)
await teams.updatePrefs('backend-team', { theme: 'dark' }); // Full overwrite write, replacing all existing preferences

await teams.delete('backend-team');   // Requires owner; cascading deletion of memberships, permission strings referencing this team become invalid immediately

Invite members

Email invitations depend on the instance's message channel being reachable; you can also use userId / phone directly.

const membership = await teams.createMembership({
    teamId: team.$id,
    roles: ['member'],                              // Free-form string; team:<teamId>/<role> is determined based on this
    email: 'newbie@example.com',                    // at least one of email / userId / phone
    url: 'https://<project-domain>/accept-invite',  // Invite redirect URL; must be in the project platform list, can be omitted with an API Key
    name: 'New Member'
});
// The secret in the response is for the invitee to confirm joining (also delivered in the invitation email); the server should forward it rather than confirm on the invitee's behalf

Member management

Membership via confirm: false is not yet in effect; check the confirmation status before relying on "already being a member" for authorization.

const members = await teams.listMemberships(team.$id);   // queries may be passed to filter pagination
const one = await teams.getMembership(team.$id, membership.$id);

await teams.updateMembership({ teamId: team.$id, membershipId: membership.$id, roles: ['admin'] });
// roles is the complete array of new roles (full-replacement semantics)

// Invitee-side confirmation (email link carries userId + secret); after confirmation confirm=true and joined is populated:
await teams.updateMembershipStatus({ teamId: team.$id, membershipId: membership.$id, userId: '<userId>', secret: '<secret>' });

await teams.deleteMembership(team.$id, membership.$id);   // The member's team:<teamId> scoped permissions expire immediately

Using for authorization

Use Role.team() in the permissions of rows / files / tables to grant access; Client SDK can only grant to teams it has already joined.

import { Permission, Role } from 'agentbase-node-sdk';

// The permissions parameter for resources such as rows / files / tables:
const permissions = [
    Permission.read(Role.team('backend-team')),             // All members
    Permission.update(Role.team('backend-team', 'owner')),  // Owner role only
];

Example Guide