Organization
Overview and use cases
The organization is the top-level collaboration unit of the Agentbase management plane: projects belong under organizations, members and roles are managed on the organization, and organization-level API Keys, plans / billing / usage are also attached at the organization dimension. The organization in the API layer corresponds to the canonical Team ID (teamId); the organization-{organizationId} in Console page URLs is the Organization public ID. The two may differ — do not mix them in automation. When to use: setting up team workspaces, member onboarding/offboarding, organization-level credentials and billing/usage governance.
Prerequisites
Console account (for the managed environment,
appbuild-sit/ the account corresponding toappbuild); Console SDK initialization is described in console-sdk/nodejs.md (see the same directory for the Java / Python / Go planes) andagentbase-console-sdk@2.8.0installation (integration.md).The Console SDK first runs
setEndpoint+setProject('console')(or the actual Console project ID of the environment), then authenticates with an email/password Session (or OAuth Browser Session → short-term JWT).Member operations require the corresponding organization role (owner / admin, etc., per the roles shown on the Console members page); organization-level usage aggregation requires the
owner,admin,analyst, orbillingrole.
Usage workflow
Create an organization: create the organization via Console or Console SDK (internally this creates a Team) and obtain the canonical
teamId; the page URL is{consoleOrigin}/console/organization-{teamId}.Members and roles: invite members to the organization Team (
Teams.createMembership, supports email / userId / phone), query withTeams.listMemberships/getMembership, adjust roles withTeams.updateMembership, handle acceptance/join status withTeams.updateMembershipStatus, remove withTeams.deleteMembership; member operations are recorded inTeams.listLogs.Organization API Key: the Console SDK's
Organizationsservice provides create / list / update / delete for organization Keys (createKey/listKeys/getKey/updateKey/deleteKey). Note: the existence of these SDK methods does not mean the target instance necessarily exposes the corresponding routes; only use the Key path when the target environment has delivered a valid Organization API Key through a supported channel, otherwise use an Owner Session or a short-term Owner JWT (for organization project governance see project-governance.md).Plans and billing (managed environments):
Organizations.getPlan/listInvoices/getInvoice/getInvoiceDownload, billing address, credits and estimates (getAvailableCredits/addCredit/estimationUpdatePlanetc.).Organization usage (2.6.0):
organizations.listUsageAggregates({ organizationId })returns standard Meter aggregation for the organization over the most recent 30 UTC days;quantity: nullmeans missing and must not be treated as 0.Capability queries:
Organizations.getScopesandOrganizations.listRegionsquery the scopes and regions available to the organization.
Key parameters and returns
| Invocation | Key parameters | Returns / notes |
|---|---|---|
| Create organization | Organization name etc. | Organization object (canonical Team ID, members, plan and other metadata) |
Teams.createMembership | teamId, roles[], email (optional) / userId (optional) / phone (optional), url (optional; invitation redirect), name (optional) | Membership (including confirmation status confirm) |
Organizations.createKey | Organization ID, name, scopes, expiry etc. | Key metadata; the secret appears only once in the create response |
Organizations.listUsageAggregates | organizationId | MeterUsageList (range: '30d', four Meters, with complete/freshnessAt/reason) |
Organizations.getScopes / listRegions | Organization ID | Available scope list / available regions (2.6.0 is default) |
Errors and boundaries
403 / insufficient permission: the current account is not a member of the target organization or the role is insufficient; cross-organization operations are always rejected.
Passing the public organizationId from Console pages as
teamIdto the API is a common mistake: the API uses the canonical Team ID.The organization API Key path is unavailable in environments where no Key has been delivered; an ordinary project API Key cannot substitute for an organization-level Key.
Member invitations only take full effect after the invitee confirms (
confirm); authorization logic that depends on "already a member" must check the confirmation status.The last owner of an organization should not be removed; handle the projects under an organization before deleting it (see overview.md and project-governance.md for project lifecycle and governance).
SDK Category Differences
Console SDK (JS,
agentbase-console-sdk@2.8.0): the primary surface for organization management (organization CRUD, members, organization Keys, plans and billing, organization usage aggregation).Console Java SDK (2.6.0): there is no
Organizationsservice under theio.agentbase.consolenamespace; organization-level operations go through the JS Console SDK or the Console UI — Java management tools only cover parallel capabilities such as projects / keys / data plane.Server / Client SDK: does not carry organization management; the only organization-related boundary in the Client SDK is organization project governance (Owner Session +
setOrganization), see project-governance.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).
Creating an organization (Teams)
An organization is internally a Team: after Console SDK Teams.create creates it, team.$id is the canonical Team ID; the REST equivalent is POST /v1/teams. Organization management does not go through the Server / Client SDK.
- Console (Node.js)
- REST (curl)
import { Client, Account, Teams, ID } from 'agentbase-console-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // Must include /v1
.setProject(process.env.APPWRITE_CONSOLE_PROJECT_ID!); // 'console' or the actual Console project ID of the environment
const account = new Account(client);
await account.createEmailPasswordSession({
email: process.env.APPBASE_OWNER_EMAIL!,
password: process.env.APPBASE_OWNER_PASSWORD!
});
const teams = new Teams(client);
const team = await teams.create({
teamId: ID.unique(),
name: 'Acme Inc'
});
// team.$id is the canonical Team ID: page URL {consoleOrigin}/console/organization-{teamId};
// For all subsequent automation use team.$id, not the page-visible organizationIdcurl -sS -X POST "$APPBASE_ENDPOINT/teams" \
-H "X-Appwrite-Project: $APPBASE_CONSOLE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"teamId":"unique()","name":"Acme Inc"}'
# 201 returns team ($id is the canonical Team ID); roles defaults to ["owner"]Members and roles (Teams)
The Console SDK manages organization Team members (organization management does not go through the Server / Client SDK); the REST equivalents are the teams domain endpoints (teams.read / teams.write scope).
- Console (Node.js)
- REST (curl)
import { Client, Account, Teams } from 'agentbase-console-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // Must include /v1
.setProject(process.env.APPWRITE_CONSOLE_PROJECT_ID!); // 'console' or the actual Console project ID of the environment
const account = new Account(client);
await account.createEmailPasswordSession({
email: process.env.APPBASE_OWNER_EMAIL!, // The current account must hold an organization management role
password: process.env.APPBASE_OWNER_PASSWORD!
});
const teams = new Teams(client);
const membership = await teams.createMembership({
teamId: '<canonical-team-id>', // canonical Team ID, not the page's public organizationId
roles: ['developer'],
email: 'bob@example.com', // At least one of email / userId / phone must be provided
url: 'https://<console-origin>/join', // Invite redirect URL (optional)
name: 'Bob'
});
// membership.confirm=false means pending the other party's confirmation; afterwards use updateMembership for roles and updateMembershipStatus for status
// Handles confirmations, removal via deleteMembership, queries via listMemberships / getMembership; audit trail via Teams.listLogscurl -sS -X POST "$APPBASE_ENDPOINT/teams/<teamId>/memberships" \
-H "X-Appwrite-Project: $APPBASE_CONSOLE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"email":"bob@example.com","roles":["developer"],"url":"https://<console-origin>/join","name":"Bob"}'
# 201 returns membership (confirm=false means pending confirmation); invitation rate limit 10 times/hour
# Query: GET /teams/{teamId}/memberships; change role: PATCH /teams/{teamId}/memberships/{membershipId}
# Joining confirmation uses PATCH /teams/{teamId}/memberships/{membershipId}/status (with the invitation secret, usually completed by the invitee); removal uses DELETE on the same pathOrganization API Key (Organizations)
Provided only by the JS Console SDK (the Java Console SDK has no Organizations service, and there is no documented REST endpoint either); the existence of these SDK methods does not mean the target instance exposes the corresponding routes.
- Console (Node.js)
const organizations = new Organizations(client); // For client initialization and authentication, see the previous card
const key = await organizations.createKey({
organizationId: '<canonical-team-id>',
name: 'ci-automation',
scopes: ['projects.read', 'projects.write']
});
console.log(key.secret); // secret appears only once in the creation response; store it immediately
// Rotation surface: listKeys / getKey / updateKey / deleteKey; other parameters such as expiry follow the SDK method signaturesPlans and billing (managed environments)
Plan / billing / credit capabilities in managed environments are provided only by the JS Console SDK (the Java Console SDK has no Organizations service, and REST has no documented endpoints); the billing address and invoice download can also be handled on Console pages.
- Console (Node.js)
const organizations = new Organizations(client); // For client initialization and authentication, see the previous card
// Plans and billing method surface (parameters follow the agentbase-console-sdk method signatures):
// organizations.getPlan({ organizationId }) // current plan
// organizations.listInvoices({ organizationId }) // invoice list
// organizations.getInvoice / getInvoiceDownload // single invoice and download
// organizations.getAvailableCredits({ organizationId }) // available credits
// organizations.addCredit / estimationUpdatePlan // top up / plan change estimateOrganization usage aggregation (2.6.0)
organizations.listUsageAggregates returns standard Meter aggregation for the organization over the most recent 30 UTC days (organization usage belongs to the management plane and is carried only by the Console SDK and the management REST API).
- Console (Node.js)
- REST (curl)
const usage = await organizations.listUsageAggregates({ organizationId: '<organizationId>' });
// Returns MeterUsageList: range '30d', four Meters (storage_bytes / bandwidth_bytes / users_total / function_executions)
// quantity: null means missing and must not be displayed as 0; complete=false means the data is not closedcurl -sS "$APPBASE_ENDPOINT/organizations/<organizationId>/usage/aggregates" \
-H "X-Appwrite-Project: $APPBASE_CONSOLE_PROJECT_ID" \
-H "X-Appwrite-JWT: $APPBASE_OWNER_JWT"
# Requires an active membership with role owner / admin / analyst / billing (Console Session or short-term JWT)Capability queries (scopes / regions)
Scope and region queries are only available in the JS Console SDK (the Java Console SDK has no Organizations service, and REST has no documented endpoints either); the input parameter is the organization ID.
- Console (Node.js)
// organizations.getScopes: takes the organization ID and returns the list of scopes available to the organization
// organizations.listRegions: takes the organization ID; 2.6.0 returns the default region
// For both input forms (positional parameters or object), refer to the agentbase-console-sdk method signaturesExample Guide
Code examples by language are gathered in the language tree
examples/; for the combined sequence of Console SDK initialization + creating a Team + creating a project + creating an API Key, see also overview.md.