Console SDK(Java)
The Java management-plane SDK (io.agentbase.console:agentbase-console-java-sdk) covers the Console / management-plane API: organization and project governance, keys and platform registration, and cross-project operations. It can be used on the same classpath as the Server SDK (../server-sdk/java.md). For Node / Python / Go planes, see nodejs.md / python.md / go.md in the same directory.
Artifacts and installation
The ZIP delivery package (not published to a Maven registry) is hosted on agentbase-sdks release v2.12.0; for the complete download, two-layer SHA256SUMS verification, and mvn install:install-file steps, see ../integration.md (Path Two). Same-named as the Server SDK's Client but in an independent namespace: in the same Java file, import only one and use the fully qualified class name for the other; the model / enum / service classes on both sides must not be mixed.
Initialization and auth mounting
import io.agentbase.console.Client;
import io.agentbase.console.services.Projects;
Client consoleClient = new Client()
.setEndpoint(System.getenv("APPBASE_ENDPOINT")) // Instance API endpoint, includes /v1
.setProject("console")
.setCookie(System.getenv("APPBASE_SESSION_COOKIE")); // Full Cookie header value
// If using an already-obtained short-lived Console JWT, replace setCookie with the next line; choose only one of the two:
// consoleClient.setJWT(System.getenv("APPBASE_CONSOLE_JWT"));setCookie receives the full Cookie request header value, not the Session ID. Load credentials from a controlled environment; do not write them into source code or logs. The user identity must still hold the corresponding permissions on the target organization/project; the existence of the setKey method does not mean all management endpoints support API Keys, and an ordinary project Key cannot substitute for Console user identity.
Typical governance calls
The methods use the positional argument style and return synchronously:
new io.agentbase.console.services.Projects(consoleClient)
.getUsageAggregates("<projectId>"); // Three-level usage (last 30 UTC days; note the method name differs from JS's listUsageAggregates)Console-only operations such as organizations, members, and platform registration (createPlatform) cannot use project API Keys.
Feature surface navigation
For the complete mapping of governance domains to services see nodejs.md "Feature surface navigation"; feature pages per domain: Organizations, Projects and Keys, Quotas, Usage, Sites and Domains, Platform Operations.
Java Console surface-specific differences:
No
Sqlservice: SQL uses the HTTP form or the JS Console SDK (../databases/sql-proxy.md).Quota and rate limit methods are provided:
Projects.getQuotaLimits/updateQuotaLimitsandgetLimits/updateLimits/deleteLimitscorrespond to/quota-limitsand/limitsrespectively; they returnObjectwith no dedicated response model. For fields and inheritance ceilings, see quotas.The three-level usage method is named
getUsageAggregates—do not guess based on the JS naming.Checked exception types are
io.agentbase.console.exceptions.AgentbaseException; usegetCode()/getType()to distinguish HTTP status and error type.
Examples by language
The following presents examples by language for each functional domain; each card can switch languages (synced across the full page).
Create a team, project, and issue a Key
Python method names are snake_case, Go uses a facade New* constructor + With* options. This domain has no direct REST call tab; for direct REST calls, see the "Quotas and rate limits" card below.
- Console (Node.js)
- Java
- Python
- Go
Before running this example, provide a short-lived management JWT for the target Console in APPBASE_ADMIN_JWT.
import { Client, Teams, Projects, ID, Scopes } from 'agentbase-console-sdk';
const token = process.env.APPBASE_ADMIN_JWT;
if (!token) throw new Error('Set APPBASE_ADMIN_JWT for the target Console');
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // https://appbuild.oceanbase.com/v1
.setProject(process.env.APPBASE_CONSOLE_PROJECT_ID ?? 'console')
.setJWT(token);
const originalPrepareRequest = client.prepareRequest;
if (typeof originalPrepareRequest !== 'function') throw new Error('Redirect control unavailable');
client.prepareRequest = function (...args) {
const request = originalPrepareRequest.apply(this, args);
request.options.redirect = 'error';
return request;
};
const teams = new Teams(client);
const team = await teams.create({ teamId: ID.unique(), name: 'My Team' });
const projects = new Projects(client);
const project = await projects.create({
projectId: ID.unique(),
name: 'todo-app',
teamId: team.$id,
});
const key = await projects.createKey({
projectId: project.$id,
name: 'setup-script',
scopes: [Scopes.UsersRead, Scopes.UsersWrite] // minimize scope
});
// key.secret is returned only once at creation// When a Team is created in a Console project, the service synchronously creates compatible organization and member records.
// Use the returned team.getId(); do not guess the Team ID from another organization's page URL.
io.agentbase.console.services.Teams teams = new io.agentbase.console.services.Teams(consoleClient);
var team = teams.create(
io.agentbase.console.ID.unique(), "My Team", java.util.List.of("owner"));
Projects projects = new Projects(consoleClient);
var project = projects.create(
io.agentbase.console.ID.unique(), "billing-service", team.getId(),
io.agentbase.console.enums.Region.DEFAULT, null, // poolTag is nullable
null, null, null, null, null, null, null, null, null, null,
null); // powercontextEnabled; for the full parameter order, refer to the current Java artifact
var key = projects.createKey(project.getId(), "ci-deploy",
java.util.List.of(io.agentbase.console.enums.Scopes.USERS_READ,
io.agentbase.console.enums.Scopes.USERS_WRITE),
null, null, null);
// Hand key.getSecret() to a controlled credential store; do not print it to the terminal or logs.from agentbase_console.services.projects import Projects
from agentbase_console.services.teams import Teams
teams = Teams(console_client) # console_client initialization see "Initialization and auth loading" above
projects = Projects(console_client)
teams.create(team_id='my-team', name='My Team', roles=['owner'])
project = projects.create(project_id='unique()', name='My Project', team_id='my-team')
key = projects.create_key(
project_id=project.id,
name='server key',
scopes=['users.read', 'users.write', 'teams.read', 'teams.write'],
key_id='unique()')
# Store the key from this creation response directly in your secret manager.// consolefacade "agentbase-console-go-sdk/agentbase"; for consoleClient initialization, see above
consoleTeams := consolefacade.NewTeams(consoleClient)
consoleProjects := consolefacade.NewProjects(consoleClient)
_, _ = consoleTeams.Create("my-team", "My Team", consoleTeams.WithCreateRoles([]string{"owner"}))
project, _ := consoleProjects.Create("unique()", "My Project", "my-team")
key, _ := consoleProjects.CreateKey(project.Id, "server key", []string{
"users.read", "users.write", "teams.read", "teams.write",
})
_ = key // Store the key from this creation response directly in your secret manager.Usage queries
Three-level aggregation (the most recent 30 UTC days) and the legacy scheme are two separate systems; method names cannot be guessed from each other (see usage).
- Console (Node.js)
- Java
- Python
- Go
// account / organizations / projects are Console SDK service instances
await account.listUsageAggregates();
await organizations.listUsageAggregates({ organizationId: '<organizationId>' });
await projects.listUsageAggregates({ projectId: '<projectId>' });// The Java Console SDK generated name is getUsageAggregates (different from JS's listUsageAggregates)
new io.agentbase.console.services.Projects(consoleClient)
.getUsageAggregates("<projectId>"); // Project level
new io.agentbase.console.services.SelfHostedOrganizations(consoleClient)
.getUsageAggregates("<organizationId>"); // Organization level (same endpoints as the JS organizations surface)
// Account level (/account/usage/aggregates) has no typed method in console-java; use a direct REST call
// The legacy /project/usage uses another business project Client to avoid overwriting the management plane Client context.
io.agentbase.console.Client projectClient = new io.agentbase.console.Client()
.setEndpoint(System.getenv("APPBASE_ENDPOINT"))
.setProject(System.getenv("APPBASE_PROJECT_ID"))
.setMode("admin")
.setCookie(System.getenv("APPBASE_SESSION_COOKIE"));
new io.agentbase.console.services.Project(projectClient)
.getUsage(java.time.Instant.now().minus(29, java.time.temporal.ChronoUnit.DAYS).toString(),
java.time.Instant.now().toString(),
io.agentbase.console.enums.ProjectUsageRange.ONE_DAY);
// The legacy interface requires startDate/endDate; setMode("admin") selects the Console user's project management context and still validates member permissions.# This document does not provide a Python SDK example for three-level usage aggregation.
# Examples in this section can use Node / Java / REST; for Python calls, check the Console SDK in use
# Use the published package's service classes, methods and parameters; do not guess from JS naming conventions.// server-go@release-2.6.0 has no three-level aggregate methods
// side; the only legacy pattern is selfhostedorganizations.GetUsage(organizationId, WithGetUsageRange).
// The Console Go face has been delivered since 2.7.0; this document does not cover its three-level aggregation usage—use Node / Java / REST instead, and do not infer from JS naming.Quotas and rate limits (Java and REST)
The Java Console SDK's Projects already provides the following positional-argument methods; the caller must have Owner permission on the organization owning the target project. For concrete fields and inheritance rules, see quotas and rate limits. Returns Object; parse according to the response fields on that page.
Projects projects = new Projects(consoleClient);
Object quotas = projects.getQuotaLimits("<projectId>");
Object limits = projects.getLimits("<projectId>");
// Modified API: updateQuotaLimits(projectId, databaseStorageLimit, storageLimit,
// databasesPerProject, tablesPerProject)
// For the parameter order of updateLimits / deleteLimits, see the quota feature page; null means the corresponding field is not modified.The same management identity can also call REST directly. The following 0 is only valid when the inheritance ceiling likewise allows unlimited amounts; do not use the example directly on projects that do not meet this condition:
- REST (curl)
# Query current quota and rate limits:
curl -sS "$APPBASE_ENDPOINT/projects/<projectId>/limits" \
-H "X-Appwrite-Project: $APPBASE_CONSOLE_PROJECT_ID" \
-b "$APPBASE_SESSION_COOKIE"
# Settings: PATCH the same path; rate-limit fields must be positive integers, and quotas are also constrained by the inherited upper limit
curl -sS -X PATCH "$APPBASE_ENDPOINT/projects/<projectId>/limits" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_CONSOLE_PROJECT_ID" \
-b "$APPBASE_SESSION_COOKIE" \
-d '{"databaseStorageLimit": 0}'
# See the “Quotas and rate limits” link above for the full field set and field-name pitfallsExample Guide
Java (Server / Console) complete call syntax: ../examples/java.md