Docs
Contents

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

Usage workflow

  1. 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}.

  2. Members and roles: invite members to the organization Team (Teams.createMembership, supports email / userId / phone), query with Teams.listMemberships / getMembership, adjust roles with Teams.updateMembership, handle acceptance/join status with Teams.updateMembershipStatus, remove with Teams.deleteMembership; member operations are recorded in Teams.listLogs.

  3. Organization API Key: the Console SDK's Organizations service 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).

  4. Plans and billing (managed environments): Organizations.getPlan / listInvoices / getInvoice / getInvoiceDownload, billing address, credits and estimates (getAvailableCredits / addCredit / estimationUpdatePlan etc.).

  5. Organization usage (2.6.0): organizations.listUsageAggregates({ organizationId }) returns standard Meter aggregation for the organization over the most recent 30 UTC days; quantity: null means missing and must not be treated as 0.

  6. Capability queries: Organizations.getScopes and Organizations.listRegions query the scopes and regions available to the organization.

Key parameters and returns

InvocationKey parametersReturns / notes
Create organizationOrganization name etc.Organization object (canonical Team ID, members, plan and other metadata)
Teams.createMembershipteamId, roles[], email (optional) / userId (optional) / phone (optional), url (optional; invitation redirect), name (optional)Membership (including confirmation status confirm)
Organizations.createKeyOrganization ID, name, scopes, expiry etc.Key metadata; the secret appears only once in the create response
Organizations.listUsageAggregatesorganizationIdMeterUsageList (range: '30d', four Meters, with complete/freshnessAt/reason)
Organizations.getScopes / listRegionsOrganization IDAvailable scope list / available regions (2.6.0 is default)

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).

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.

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 organizationId

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).

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.listLogs

Organization 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.

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 signatures

Plans 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.

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 estimate

Organization 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).

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 closed

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.

// 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 signatures

Example Guide