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
Server API Key:
teams.read/teams.write; clients create / manage their own teams with a user Session.Inviting members requires a reachable message channel (email invitations depend on instance SMTP), or use
userIddirectly.
Usage workflow
Create team:
teams.create({ teamId, name, roles })(rolesoptional) — the creator automatically becomes a member and holds the role inroles(includingowner);ID.unique()or a custom ID.Query / maintain:
teams.list()(current user's teams),teams.get(teamId),teams.update(teamId, name)(nameoptional) (including prefs maintenance:getTeamPrefs/updateTeamPrefs),teams.delete(teamId)(requires owner).Invite member:
teams.createMembership({ teamId, roles, email , userId, phone, url, name })(email,userId,phone,url,nameall optional) — at least one of email / userId / phone;urlis the redirect address for accepting the invitation; the new member must confirm (confirm) before membership fully takes effect.Member management:
listMemberships(teamId, queries)(queriesoptional),getMembership,updateMembership({ teamId, membershipId, roles })to adjust roles,updateMembershipStatus(handles invitation acceptance / join status),deleteMembershipto remove.Using for authorization: use
Permission.read(Role.team(teamId))(optionally with member roleRole.team(teamId, 'owner')) in row / filepermissions; Client SDK can only grant to teams it has already joined (see permissions.md).
Key parameters and returns
| Call | Key parameters | Returns |
|---|---|---|
create | teamId, name, roles (optional; creator role) | Models.Team ($id, name, total) |
createMembership | teamId, roles[], email (optional)/userId (optional)/phone (optional), url (optional), name (optional) | Models.Membership (confirm status, roles) |
updateMembership | teamId、membershipId、roles[] | Membership |
updateMembershipStatus | teamId, membershipId, userId, secret | Membership (the email invitation link carries credentials) |
listMemberships | teamId, queries (optional) | MembershipList |
Errors and boundaries
Invitations require the other party's confirmation: membership via
confirm: falseis not yet in effect; authorization that relies on "already being a member" must check the confirmation status.Deleting a team requires the
ownerrole; transfer roles before removing the last owner.Client SDK cannot grant row authorization to a team it has not joined (401,
hasRoleconstraint); cross-team authorization is done server-side.The acceptance link domain for email invitations must be reachable within the project's Platform (browser redirect scenario).
Team member counts and team counts are subject to project quotas; bloated teams with many members increase authorization maintenance costs; for fine-grained scenarios combine with Function proxies (permissions.md).
SDK Category Differences
Client SDK (Web):
teams.create/list/get/update/delete+ member management (user Session, manages the teams the user belongs to).Server SDK: the same set of methods (administrator view, can manage all teams in the project); Java is a synchronous typed model, Python is snake_case.
Console SDK: the
Teamsservice in the Console context operates on organizational Teams (members / invitations), not in-project teams; do not mix theteamIdof the two contexts.Difference entry points: client-sdk/web.md,
server-sdk/nodejs.md.
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
- Node.js (Server)
- Web (user session)
- Java
- Python
- Go
- REST (curl)
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()import { Client, Teams, ID } from 'agentbase-web-sdk'; // Prerequisite: the user is logged in
const teams = new Teams(client);
// A user Session can only manage teams it belongs to; granting a row/file to a team not joined returns 401 (hasRole constraint)
const team = await teams.create({ teamId: ID.unique(), name: 'my-team' });import io.agentbase.ID;
import io.agentbase.models.Team;
import io.agentbase.services.Teams;
Teams teams = new Teams(client); // For client initialization, see server-sdk/java.md
Team<Map<String, Object>> team = teams.create(ID.unique(), "backend", List.of("owner"));from agentbase.services.teams import Teams
teams = Teams(client) # client initialization see server-sdk/python.md
team = teams.create(team_id='backend-team', name='backend', roles=['owner'])teams := agentbase.NewTeams(client) // facade constructor; client is already loaded with an API Key
team, err := teams.Create("backend-team", "backend", teams.WithCreateRoles([]string{"owner"}))curl -sS -X POST "$APPBASE_ENDPOINT/teams" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"teamId":"backend-team","name":"backend","roles":["owner"]}'
# roles is the creator's roles, defaulting to ["owner"]; teamId is at most 36 charactersQuery / maintain
Server SDK lists all teams in the project from the administrator view; Web (user Session) only sees the teams the user belongs to.
- Node.js (Server)
- Web (user session)
- Java
- Python
- Go
- REST (curl)
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 immediatelyconst mine = await teams.list(); // Current user's teams
const team = await teams.get('my-team');
await teams.update('my-team', 'New Name');
await teams.delete('my-team');teams.list(null, null, null); // All teams within the project, supports queries / search / total
var team = teams.get("backend-team");
teams.updateName("backend-team", "backend-core"); // Team ID is immutable; only renaming is allowed
teams.getPrefs("backend-team"); // Team preferences (free-form key-value JSON)
teams.updatePrefs("backend-team", Map.of("theme", "dark")); // Full overwrite write, replacing all existing preferences
teams.delete("backend-team"); // Requires owner; cascading deletion of memberships, permission strings referencing this team become invalid immediatelyteams.list() # All teams in the project, supports queries / search
team = teams.get(team_id='backend-team')
teams.update_name(team_id='backend-team', name='backend-core') # Team ID is immutable; only renaming is allowed
teams.get_prefs(team_id='backend-team') # Team preferences (free-form key-value JSON)
teams.update_prefs(team_id='backend-team', prefs={'theme': 'dark'}) # Full overwrite write (as opposed to merge semantics)
teams.delete(team_id='backend-team') # Requires owner; cascading deletion of memberships, permission strings referencing this team become invalid immediately_, err = teams.List() // All teams in the project, supports queries / search
team, err := teams.Get("backend-team")
_, err = teams.UpdateName("backend-team", "backend-core") // Team ID is immutable; only renaming is allowed
_, err = teams.GetPrefs("backend-team") // Team preferences (free-form key-value JSON)
_, err = teams.UpdatePrefs("backend-team", map[string]interface{}{"theme": "dark"}) // Full overwrite write
_, err = teams.Delete("backend-team") // Requires owner; cascading deletion of memberships, permission strings referencing this team become invalid immediately
_ = teamcurl -sS "$APPBASE_ENDPOINT/teams" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# Single team: GET /teams/{teamId}; rename: PUT /teams/{teamId} (body: name, ID is immutable)
# Team preferences: GET /teams/{teamId}/prefs; PUT /teams/{teamId}/prefs (body: prefs, full overwrite)
# Delete (cascades to memberships, owner required): DELETE /teams/{teamId}Invite members
Email invitations depend on the instance's message channel being reachable; you can also use userId / phone directly.
- Node.js (Server)
- Web (user session)
- Java
- Python
- Go
- REST (curl)
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 behalfconst membership = await teams.createMembership({ teamId: team.$id, roles: ['member'], email: 'newmember@example.com' });import io.agentbase.models.Membership;
Membership membership = teams.createMembership(
team.getId(),
List.of("member"), // roles
"newbie@example.com", // email (at least one of userId / phone)
null, // userId
null, // phone
"https://app.example.com/accept", // url: the redirect address for accepting the invitation
null // name
);membership = teams.create_membership(
team_id='backend-team',
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 behalfmembership, err := teams.CreateMembership("backend-team", []string{"member"}, // roles is a positional parameter; team:<teamId>/<role> is determined by this
teams.WithCreateMembershipEmail("newbie@example.com"), // at least one of email / userId / phone
teams.WithCreateMembershipUrl("https://<project-domain>/accept-invite"), // Must be in the project's platform list
teams.WithCreateMembershipName("New Member"))
_ = membership // The secret in the response is for the invitee to confirm joining; the server should forward it rather than confirm on their behalfcurl -sS -X POST "$APPBASE_ENDPOINT/teams/backend-team/memberships" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"email":"newbie@example.com","roles":["member"],"url":"https://example.com/accept-invite","name":"New Member"}'
# at least one of email / userId / phone; url only allows hostnames on the project platform list (prevents open redirects)
# Rate limit 10 times/hour; the invite secret only appears in this endpoint's response and in the invitation emailMember management
Membership via confirm: false is not yet in effect; check the confirmation status before relying on "already being a member" for authorization.
- Node.js (Server)
- Web (user session)
- Java
- Python
- Go
- REST (curl)
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 immediatelyconst members = await teams.listMemberships('my-team');
await teams.updateMembership({ teamId: 'my-team', membershipId: '<membershipId>', roles: ['admin', 'member'] });
await teams.deleteMembership('my-team', '<membershipId>');
// Invite confirmation is completed on the invitee's sideteams.listMemberships(team.getId(), null, null, null);
var one = teams.getMembership(team.getId(), membership.getId());
teams.updateMembership(team.getId(), membership.getId(), List.of("admin")); // roles is the complete array of new roles (full replacement)
// The invitee confirms with the userId + secret carried in the invitation email (public endpoint); after confirmation confirm=true and joined is populated:
teams.updateMembershipStatus(team.getId(), membership.getId(), "<userId>", "<secret>");
teams.deleteMembership(team.getId(), membership.getId());members = teams.list_memberships(team_id='backend-team') # queries may be passed to filter pagination
one = teams.get_membership(team_id='backend-team', membership_id='<membership_id>')
teams.update_membership(team_id='backend-team', membership_id='<membership_id>',
roles=['admin']) # roles is the complete array of new roles (full replacement)
# Invitee-side confirmation (email link carries userId + secret); after confirmation, confirm=True and joined is populated:
teams.update_membership_status(team_id='backend-team', membership_id='<membership_id>',
user_id='<user_id>', secret='<secret>')
teams.delete_membership(team_id='backend-team', membership_id='<membership_id>') # team:<teamId>-scoped permissions take effect immediatelymembers, err := teams.ListMemberships("backend-team") // queries may be passed to filter pagination
one, err := teams.GetMembership("backend-team", "membership-id")
_, err = teams.UpdateMembership("backend-team", "membership-id", []string{"admin"}) // roles is a positional parameter, the complete array of new roles (full replacement)
// The invitee confirms with the userId + secret carried in the invitation email; after confirmation confirm=true:
_, err = teams.UpdateMembershipStatus("backend-team", "membership-id", "user-123", "<secret>")
_, err = teams.DeleteMembership("backend-team", "membership-id") // team:<teamId>-scoped permissions take effect immediately
_, _ = members, onecurl -sS "$APPBASE_ENDPOINT/teams/backend-team/memberships" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# Single item: GET /teams/{teamId}/memberships/{membershipId}
# Adjust roles (full replacement): PATCH /teams/{teamId}/memberships/{membershipId} (body: roles)
# Remove member: DELETE /teams/{teamId}/memberships/{membershipId}
# Invitee confirms joining with the secret: PATCH /teams/{teamId}/memberships/{membershipId}/status (body: userId + secret)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.
- Node.js (Server)
- Web (user session)
- Java
- Python
- Go
- REST (curl)
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
];import { Permission, Role } from 'agentbase-web-sdk';
const permissions = [
Permission.read(Role.team('my-team')),
Permission.delete(Role.team('my-team', 'owner')),
];
// The Client SDK can only grant access to teams it has already joined; granting to an unjoined team returns 401 (hasRole constraint)// The permissions parameter for resources such as rows / files / tables (Permission / Role and Query / ID are both in the io.agentbase package):
List<String> permissions = List.of(
Permission.read(Role.team("backend-team")), // All members
Permission.update(Role.team("backend-team", "owner"))); // Owner role only# permissions parameter for resources such as rows / files / tables (Permission / Role constructors come from the agentbase package):
permissions = [
Permission.read(Role.team('backend-team')), # All members
Permission.update(Role.team('backend-team', 'owner')), # Owner role only
]
# You can also pass a syntax string list directly, e.g. 'read("team:backend-team")'import (
"appbase-go-sdk/permission"
"appbase-go-sdk/role"
)
// The permissions parameter for resources such as rows / files / tables: SDK builders generate permission strings
// (permission.Read/Update/Delete(role) + role.Team(id, role), returns string):
permissions := []string{
permission.Read(role.Team("backend-team", "")), // All members
permission.Update(role.Team("backend-team", "owner")), // Owner role only
}
_ = permissionscurl -sS -X POST "$APPBASE_ENDPOINT/tablesdb/<DATABASE_ID>/tables" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"tableId":"comments","name":"Comments","rowSecurity":true,"permissions":["read(\"users\")","update(\"team:backend-team/owner\")"]}'
# Permission strings appear in the permissions array of creation endpoints for tables / rows / buckets / files; team:<teamId>/<role> denotes a team member roleExample Guide
Per-language usage is centralized in the language tree
examples/; for Java'screateMembership(email / userId / roles / url parameter positions) and Python'steams.create(team_id/roles=['owner']), seeskills/ob-agentbase/references/server-sdks/java.mdandskills/ob-agentbase/references/server-sdks/python.md.