CLI, SDK, And APIs

AI Cloud integrations should use committed contracts and generated clients where available. The UI, CLI, SDKs, and APIs share the same tenant, project, auth, idempotency, and error model.

Use CLI And SDK Guide for concrete commands, curl examples, TypeScript fetch examples, and SDK readiness checks.

CLI

Use the CLI for:

• local automation;
• smoke checks;
• repeatable launch or cleanup flows;
• CI jobs that need product-level verification;
• support readback that should not require direct database access.

CLI workflows should preserve the same behavior as API calls: bearer auth, project context, idempotency for retryable mutations, and structured errors. After login, the CLI stores its local config under ~/.gpuaas-cli/config.json with user-only permissions. See CLI And SDK Guide for the full login, logout, local storage, and SDK credential-handling model.

Current command name:

gpuaas --base-url https://api.<your-ai-cloud-domain> auth login
gpuaas auth whoami
gpuaas context show
gpuaas catalog list --output table
gpuaas allocations list --status active --output table

SDK

SDKs should wrap contract-generated API shapes. Keep pagination, retries, project context, and error handling consistent with the REST contract. SDKs should receive tokens from the host application, service-account flow, or identity layer. They should not silently read a developer's CLI config unless they are intentionally building a local developer tool.

Use SDKs when an application needs to:

• list projects or runtimes;
• launch or release work;
• inspect app/catalog state;
• automate tenant or project operations;
• integrate with endpoint or route metadata.

Use the REST contract as the compatibility boundary. Generated SDKs should not invent hidden project context, retry, or error semantics that the API does not publish.

For product terminology used in API names and payloads, start with Concepts.

Authentication

• Use bearer authentication.
• Do not place tokens in query strings.
• Do not paste tokens into screenshots, logs, tickets, or support messages.
• Treat browser WebSocket auth as a special protocol boundary, not a pattern for normal API calls.

Service Account Tokens

Service accounts are the preferred API identity for automation. The lifecycle is:

1. A tenant or project admin creates the project-scoped service account.
2. The admin stores the one-time client secret in the automation secret store.
3. Automation calls the service-account token endpoint to mint a short-lived bearer token.
4. API calls include a bearer-auth header and the matching X-Project-ID when the operation is project-scoped.

Useful endpoints:

Operation	Endpoint
List service accounts	GET /api/v1/projects/{project_id}/service-accounts
Create service account	POST /api/v1/projects/{project_id}/service-accounts
Rotate credential	POST /api/v1/projects/{project_id}/service-accounts/{service_account_id}/rotate-key
Disable service account	POST /api/v1/projects/{project_id}/service-accounts/{service_account_id}/disable
Delete service account	DELETE /api/v1/projects/{project_id}/service-accounts/{service_account_id}
Mint token	POST /api/v1/auth/service-account/token

Never log the client secret or minted access token. Use separate service accounts per automation purpose when ownership, billing, or blast radius should be separated.

Project Context

Most operations run inside tenant and project context. When an endpoint requires project scope, send the expected project context and make sure the selected project matches the user intent.

Idempotency And Retries

Retryable mutations should send an idempotency key. This prevents a network retry from creating duplicate work. If an idempotency conflict occurs, reload state and retry only after deciding whether the intended input changed.

Structured Errors

Errors use stable codes and correlation IDs.

{
  "code": "validation_error",
  "message": "human-readable message",
  "correlation_id": "corr-example",
  "details": {}
}

Use the correlation ID when asking for support. Do not include private tokens, keys, one-time codes, or raw provider payloads.

Events

Events use a typed envelope with event ID, event type, timestamp, version, correlation ID, and payload. Consumers should handle retry and duplicate delivery safely.

{
  "event_id": "uuid",
  "event_type": "domain.event",
  "occurred_at": "2026-07-08T00:00:00Z",
  "version": "1.0",
  "correlation_id": "corr-example",
  "payload": {}
}

API Reference Scope

The public API reference should focus on user, tenant-admin, app, and partner-safe operations. Platform-only administrative operations are documented for authorized internal teams in the protected engineering portal.