SuperAgent API

Projects, isolation, and service accounts

A project keeps one product, customer, or environment separate from another. Its wallets, approvals, runs, files, webhooks, database data, usage, and audit history stay inside that boundary.

Do you need a project?

Use one when you have more than one customer, app, or environment. For a small first integration, the account-level default is enough.

Create a project

Use an account-level key with projects:write:

const created = await hive.projects.create(
  {
    name: "Acme production",
    description: "Managed backend for the Acme application",
  },
  { idempotencyKey: "project-acme-production" },
);

if (!created.ok) throw new Error(created.error);
const projectId = created.project.id;

Projects can be listed, read, renamed, and archived. Archiving prevents new requests from selecting the project. It does not silently move its resources to another project.

Give one workload its own key

Create a child key with projectId. The project binding cannot be removed or changed, and every descendant inherits it.

const worker = await hive.apiKeys.create(
  {
    label: "Acme research worker",
    projectId,
    scopes: [
      "services:read",
      "services:invoke",
      "runs:read",
      "runs:write",
      "artifacts:read",
    ],
    allowedServices: ["hive-research"],
    allowedOperations: [
      "capabilities.list",
      "services.invoke.hive-research.analyses.create",
      "runs.create.hive-research.analyses.create",
      "runs.read",
      "artifacts.list",
      "artifacts.content.read",
    ],
  },
  { idempotencyKey: "key-acme-research-worker-v1" },
);

This is the recommended service-account pattern: one project-bound key per workload, with exact scopes, services, operations, expiry, and limits.

Advanced: temporary project selection and isolation rules

Select a project with an account key

An account-level key can select an active project for one request:

X-HivemindOS-Project: project_...

The TypeScript client sends that header automatically when constructed with projectId:

const acme = new HivemindOSClient({
  apiKey: process.env.HIVEMINDOS_ACCOUNT_API_KEY!,
  projectId: "project_...",
});

A project-bound key rejects a different project header. Use separate client instances for separate projects and never accept an unvalidated project id directly from an end-user request.

Isolation rules

Resource ids are meaningful only inside their account and project.
An id from one project returns not found from another project.
Idempotency keys are isolated by project and API key.
Webhooks receive only events from their project and allowed services.
Usage and audit queries report only the selected project.
Managed databases receive the same project boundary as every other resource.
A project-bound key cannot create another project or an account-level child key.

Environment pattern

Create separate projects for development, staging, and production. Use separate API keys and webhook destinations for each. Do not reuse a production project for tests: project isolation protects data, but it cannot tell whether a valid production key was used accidentally.

Next: restrict exact operations, set per-endpoint limits, or inspect usage and audit events.