Gazebo
    ServicesAgentsVaultsDocsWritingPricing
    Log inSign up
    Log in

    Getting Started

    • Introduction
    • How Gazebo works
    • Core concepts
    • Quickstart

    Agent Access

    • Access profiles
    • Bearer tokens
    • Audit logs

    MCP

    • Overview
    • Cursor
    • Claude Desktop
    • Claude Code
    • ChatGPT / Codex
    • Devin / Windsurf
    • Any MCP client
    • Get credential reference

    Authorization

    • Agent Consent Flow

    REST API

    • Overview
    • Authentication
    • Services
    • Agents
    • Access policies
    • Audit events
    • Consent administration
    • Agent credential access
    • Errors and limits

    Developer Tools

    • TypeScript SDK
    • CLI

    Security

    • Overview
    • Encryption model
    • Credential storage
    • Audit and compliance
    • Responsible disclosure
    Documentation

    Getting Started

    • Introduction
    • How Gazebo works
    • Core concepts
    • Quickstart

    Agent Access

    • Access profiles
    • Bearer tokens
    • Audit logs

    MCP

    • Overview
    • Cursor
    • Claude Desktop
    • Claude Code
    • ChatGPT / Codex
    • Devin / Windsurf
    • Any MCP client
    • Get credential reference

    Authorization

    • Agent Consent Flow

    REST API

    • Overview
    • Authentication
    • Services
    • Agents
    • Access policies
    • Audit events
    • Consent administration
    • Agent credential access
    • Errors and limits

    Developer Tools

    • TypeScript SDK
    • CLI

    Security

    • Overview
    • Encryption model
    • Credential storage
    • Audit and compliance
    • Responsible disclosure
    DocsDeveloper Tools

    TypeScript SDK

    Documentation index (llms.txt)View as Markdown

    Use the Gazebo TypeScript SDK for server-side account automation and agent-scoped credential retrieval. The CLI uses the same SDK; MCP remains available for MCP-compatible clients.

    Installation

    The SDK is dependency-free, ESM-only and intended for server-side Node.js. Its current minimum is Node.js 20; use a maintained, security-patched Node.js 22 or 24 release for new applications. Do not put account or agent tokens in browser bundles.

    npm install @gazebohq/sdk
    

    Import Gazebo and, when needed, GazeboError from @gazebohq/sdk. The package includes compiled JavaScript and TypeScript declarations.

    Available on npm. View the source and examples on GitHub. The SDK and CLI are MIT-licensed.

    Authentication

    Connect an application's users

    The account-connection flow adds an explicit consent mode alongside the manual account/agent modes below. Your application supplies its own authenticated callback and encrypted per-user storage with shared locking.

    Register an application public ES256 key, exact callback and gazebo.credentials.read scope in Agent Consent Flow. Your backend uses the server-only @gazebohq/sdk/consent helpers to start a signed request, retain session-bound state and PKCE, and complete the one-time callback. The user approves specific service/key pairs and chooses the existing agent expiry.

    Follow the complete account-connection guide for application registration, startConnection, completeConnection, authenticated callback routes, per-user storage adapters, renewal, disconnect and error handling. The example below shows runtime use after that setup; it is not the entire onboarding flow.

    import { Gazebo } from "@gazebohq/sdk";
    import { createConnectionTokenProvider } from "@gazebohq/sdk/consent";
    
    const agent = new Gazebo({
      endpoint: "https://app.gazebohq.com",
      auth: {
        type: "consent",
        tokenProvider: createConnectionTokenProvider({
          endpoint: "https://app.gazebohq.com",
          clientId,
          privateKeyJwk,
          store: encryptedPerUserConnectionStore,
        }),
      },
    });
    await agent.credentials.get("github", { keyName: "api_key" });
    

    The application must supply encrypted persistent storage and a cross-worker lock for each authenticated user's connection. Helpers renew one-hour access tokens automatically; rotating renewal credentials expire after 30 inactive days. Both are capped by the user-selected approval expiry. Persisted operation IDs allow identical retries for 60 seconds; older lost-response recovery requires reconnecting. Use disconnectStoredConnection to block local use and retry remote revocation if Gazebo is unavailable.

    Consent-mode operations are named-key retrieval and connection identity/disconnect—not account administration, bulk retrieval or MCP. Revoking the approval or agent, disabling the client, or reaching the expiry stops future retrieval and renewal.

    The retrieving runtime and its host receive the selected provider key. If retrieval happens in a separate trusted backend, the model need not receive it; direct agent retrieval delivers it to the agent runtime. This does not hide credentials from an untrusted retrieving host, invalidate keys already retrieved, or enforce provider operations after delivery. It is not an OAuth-compatibility claim. See Agent Consent Flow and the package's examples/connect-application.ts for the backend integration contract.

    Manual token modes

    Read the authentication guide for obtaining and protecting manual tokens. Account, agent and delegated consent tokens are not interchangeable.

    • Account client: trusted administration, using an account API token supplied by your secret manager.
    • Agent client: credential retrieval for one agent, using its agent token.

    The SDK does not discover tokens from environment variables automatically. Your application supplies the token explicitly. Generating a replacement account token revokes the previous one; do not rotate a shared automation token just to try an example.

    Account quickstart

    This read-only example verifies authentication and reports counts without logging account details or credentials. Run it in a server-side ESM application with GAZEBO_ACCOUNT_TOKEN supplied through your environment or secret manager.

    import { Gazebo } from "@gazebohq/sdk";
    
    const token = process.env.GAZEBO_ACCOUNT_TOKEN;
    if (!token) throw new Error("Set GAZEBO_ACCOUNT_TOKEN securely.");
    
    const gazebo = new Gazebo({
      endpoint: "https://app.gazebohq.com",
      auth: { type: "account", token },
    });
    
    await gazebo.account.get();
    const services = await gazebo.services.list();
    const agents = await gazebo.agents.list();
    
    console.log({
      connectedServiceCount: services.length,
      activeAgentCount: agents.length,
    });
    

    Agent credential quickstart

    Connect a service in the dashboard, create an agent, and enable that service for the agent before retrieving its credential. This example assumes service stripe, a key named api_key, and a policy permitting credential release for the declared GET method.

    import { Gazebo } from "@gazebohq/sdk";
    
    export async function getStripeApiKey(): Promise<string> {
      const token = process.env.GAZEBO_AGENT_TOKEN;
      if (!token) throw new Error("Set GAZEBO_AGENT_TOKEN securely.");
    
      const agent = new Gazebo({
        endpoint: "https://app.gazebohq.com",
        auth: { type: "agent", token },
      });
    
      const result = await agent.credentials.get("stripe", {
        method: "GET",
        keyName: "api_key",
      });
    
      // Pass directly to your server-side integration; never log this value.
      return result.credentials.api_key;
    }
    

    The response contains one sensitive credential in credentials. Without keyName, the server selects the primary credential, preferring api_key. Without method, credential retrieval defaults to GET.

    Method policies govern credential release, not subsequent provider calls. Once a credential is released, provider-side scopes and IAM must restrict what it can do. The SDK does not execute provider requests or automatically poll for approval.

    Trust the runtime: the SDK returns the actual stored provider credential to the retrieving runtime. If another developer hosts that runtime, their infrastructure receives it. Use narrowly scoped provider credentials and keep each user's access separate; account administration tokens are not runtime tokens. Manual agent-token setup is distinct from the SDK's consent helpers described above; applications supply their own sign-in, connection UI, callback and secure storage.

    Revocation and audit limits: revoking an agent blocks future retrieval, not use of provider keys already retrieved. If a key is compromised, revoke or rotate it at the provider. Gazebo logs credential access, not every subsequent provider action.

    You can retrieve credentials in a trusted backend and return only action results to the model. The backend still receives the provider key and must be isolated from agent-controlled execution.

    Supported operations

    Account clients expose:

    OperationPurpose
    account.get()Read account identity and feature availability
    services.list()List connected service metadata, not credential values
    services.testCredentials(service, credentials)Test supplied credentials without saving
    services.replaceCredentials(service, credentials)Replace the service's complete named-key set
    services.deleteCredentials(service)Remove all stored credentials for the service
    agents.list()List active agents without their tokens
    agents.create({ name, expiresAt? })Create an agent; return its token once
    agents.delete(agentId)Revoke that agent
    access.get(agentId)Read service access policies
    access.set(agentId, service, { enabled, methods })Replace a service policy with explicit methods
    auditEvents.list(filters?)Read one page of credential-access events

    Agent clients expose only credentials.get(service, options?). The separation applies to TypeScript and runtime objects; server authorization remains the security boundary.

    Consent clients expose credentials.get(service, { keyName }), connection.get() and connection.disconnect(). Named-key selection is required. Backend-managed connections should use disconnectStoredConnection to also block local renewal and token use while remote revocation is retried.

    Service credential operations require SDK 0.1.2 or newer. Consent administration and arbitrary dashboard endpoints are not SDK operations. See the REST API for its separately documented capabilities.

    Service credential management

    Use an account client and supply a nonempty array of { keyName, value } objects from trusted server-side storage. Do not print those objects or put credentials in a model conversation.

    const result = await gazebo.services.testCredentials("stripe", credentials);
    if (!result.ok) {
      throw new Error("Credential verification failed");
    }
    if (!result.verified) {
      throw new Error("Remote verification is not available");
    }
    // Only after the owner approves replacing the complete credential set:
    await gazebo.services.replaceCredentials("stripe", credentials);
    

    Here credentials is the complete intended named-key array supplied by your application, not a credential-fetching SDK operation.

    Replacement is not a merge: it removes omitted keys and replaces the whole service set. Existing agents may depend on those keys. deleteCredentials(service) removes the entire set. Neither operation revokes keys at the provider or invalidates previously retrieved copies.

    Testing does not save. Its result distinguishes verified success, skipped remote verification (ok: true, verified: false) and failed verification (ok: false). Errors are deliberately generic and omit raw provider text. HTTP/network failures still throw GazeboError; HTTP 200 alone is not evidence of successful verification.

    Names are normalised to lowercase; duplicate/empty credential names and empty values are rejected before HTTP. These are generic stored-credential operations, not a provider OAuth connect/refresh flow. Test and replacement are separate requests, without conditional-create guarantees or automatic rollback.

    Agent creation and policy changes

    Creating an agent returns a sensitive token once. Store it in your secret manager without logging or serializing the entire response. Optional expiresAt is a UTC ISO timestamp; omitting it creates an agent without an expiration.

    Using the account client from the quickstart:

    const created = await gazebo.agents.create({
      name: "GET credential retrieval",
      expiresAt: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
    });
    
    // Securely store created.token before proceeding. Do not console.log(created).
    await gazebo.access.set(created.id, "stripe", {
      enabled: true,
      methods: ["GET"],
    });
    
    // Later, when this integration is no longer needed:
    await gazebo.agents.delete(created.id);
    

    Policy updates replace the existing policy. Always provide a nonempty methods list, including when setting enabled: false. Supported methods are GET, POST, PUT, PATCH and DELETE. Revocation blocks subsequent credential retrieval; it does not invalidate a provider credential already released.

    Audit pagination

    Each call returns { events, nextCursor, hasMore }. Pagination is explicit:

    const filters = { service: "stripe", limit: 50 };
    let page = await gazebo.auditEvents.list(filters);
    let eventCount = page.events.length;
    
    while (page.hasMore && page.nextCursor) {
      page = await gazebo.auditEvents.list({
        ...filters,
        cursor: page.nextCursor,
      });
      eventCount += page.events.length;
    }
    
    console.log({ eventCount });
    

    Filters are limit (integer 1–200), cursor, agentId, service, outcome (success, denied or not_found), from and to. Date filters are timestamp strings. Keep filters unchanged when advancing opaque cursors. Returned timestamps remain strings, not JavaScript Date objects. Audit records may contain identifying information; do not publish raw responses.

    Endpoint, timeout and cancellation

    Set the origin, not an API resource URL. The SDK appends its supported paths and preserves an optional endpoint path prefix:

    new Gazebo({ endpoint: "https://app.gazebohq.com", auth });
    new Gazebo({ endpoint: "http://localhost:8787", auth });
    

    Here auth is the same explicit { type, token } configuration shown above. Local targeting demonstrates interface configurability only: a local broker is not yet implemented and cloud/local parity is not yet verified.

    The default timeout is 10 seconds, including response-body reads. Override it with constructor timeoutMs. Every operation accepts request options containing an AbortSignal; credential retrieval accepts signal alongside method and keyName.

    const controller = new AbortController();
    const pending = gazebo.agents.list({ signal: controller.signal });
    controller.abort();
    await pending; // Rejects with a cancelled GazeboError.
    

    Use HTTPS remotely. Core API requests do not retry, automatically paginate, follow redirects, use cookie authentication or log responses. The server-side connection helper's bounded renewal retry is separate.

    Errors and troubleshooting

    import { GazeboError } from "@gazebohq/sdk";
    
    try {
      await gazebo.agents.list();
    } catch (error) {
      if (error instanceof GazeboError) {
        console.error({ code: error.code, status: error.status });
      } else {
        throw error;
      }
    }
    

    Error codes are http, network, timeout, cancelled, invalid_response and auth_mode. HTTP failures expose status and, when present, the raw retryAfter header. Input validation throws TypeError.

    details contains the parsed server response, is non-enumerable and is omitted by JSON serialization. Direct access can still reveal sensitive fields: inspect deliberately, never log it blindly. Unknown additive response fields are preserved; missing or invalid required fields cause invalid_response.

    • 401: check the token type, expiration and revocation.
    • 403: inspect the agent's enabled service and declared-method policy; do not retry unchanged or invent approval polling.
    • 404: check the service identifier and named key.
    • 429: follow the API limits guidance; core API requests do not retry automatically.

    Compatibility and support

    SDK package versions and REST API versions are separate. Account operations use the supported /api/v1 resources; agent credential retrieval uses /api/agents. Do not assume every REST or dashboard capability exists in the SDK. Consult API errors and compatibility before depending on a response contract.

    Public npm installation for version 0.1.1, local archive installation, TypeScript consumption and controlled cloud workflows have been verified. This does not certify every operating system, every example, real-provider credential usage or a local broker.

    For help, contact hello@gazebohq.com with your runtime version, package version, error code and HTTP status. Do not send tokens, credential values or raw account/audit responses. Continue with the CLI guide for shell automation.

    Explore Gazebo

    Gazebo gives each agent an independent access boundary around your agent credentials, with controls for approval, auditing, and revocation.

    Scoped identities for AI agentsGive every agent only the credentials it needs.Credential security and audit controlsSee how access is protected, recorded, and revoked.
    Errors and limitsCLI
    Gazebo

    Credential management for AI agents. Control credential retrieval, review access logs, and revoke an agent’s future retrieval without rotating shared API keys.

    Gazebo

    • Account
    • Demo
    • Pricing

    Explore

    • Services
    • Agents
    • Vaults

    Developers

    • Docs
    • SDK
    • CLI
    • API
    • MCP

    Content

    • Writing
    • Topics
    • Blog

    Company

    • About
    • Contact
    • hello@gazebohq.com

    © 2026 Gazebo. All rights reserved.

    PrivacyTermsSecurity