Account and organization

Account resources are the organization-level controls around your BCTRL project. Use them to identify the authenticated actor, issue API keys, isolate customers, configure notification destinations, and inspect usage.

The SDK exposes these resources both directly and under bctrl.account:

Choose whichever style reads best for your application. The methods and response shapes are the same.

Check the authenticated actor

whoami() tells you which API key made the request and which scope the request is using.

1
const me = await bctrl.auth.whoami();
2
3
console.log(me.scope); // "organization" or "subaccount"
4
console.log(me.organizationId);
5
console.log(me.subaccountId); // null for an organization-scoped key
6
console.log(me.keyId);

The response also includes the account plan, email, defaultSpaceId, and effectiveScope. effectiveScope describes the scope after a request is narrowed with BCTRL-Subaccount-Id or bctrl.withSubaccount().

whoami() fields

AuthEffectiveScope has the same scope identifiers plus the effective default Space:

1
type AuthEffectiveScope = {
2
  scope: "organization" | "subaccount";
3
  organizationId: string;
4
  subaccountId: string | null;
5
  defaultSpaceId: string | null;
6
};

API keys

Create a key for the organization, or pass subaccountId to create a key scoped to a subaccount.

1
const created = await bctrl.apiKeys.create({
2
  name: "production",
3
  subaccountId: "subacct_123", // omit for an organization key
4
  expiresAt: "2027-01-01T00:00:00.000Z",
5
});
6
7
const { data: key, secret } = created;
8
9
console.log(key.id, key.keyPrefix);
10
console.log(secret); // save it now; it is returned only once

The create response is { data, secret }. BCTRL never returns the plaintext secret again. Store it in your secret manager and rotate a key by creating the replacement before deleting the old key.

1
const keys = await bctrl.apiKeys.list({ type: "organization" });
2
for await (const key of bctrl.apiKeys.iter({ subaccountId: "subacct_123" })) {
3
  console.log(key.id, key.lastUsedAt);
4
}
5
6
await bctrl.apiKeys.delete(key.id);

API key fields

Subaccounts

Use a subaccount when one organization needs isolated customers, spaces, API keys, limits, and usage. Create the subaccount once, then use its ID when creating or scoping resources.

1
const subaccount = await bctrl.subaccounts.create({
2
  name: "Acme Corp",
3
  externalId: "customer_42",
4
  metadata: { plan: "growth" },
5
  limits: {
6
    maxSpaces: 10,
7
    maxActiveRuns: 25,
8
    monthlyCreditLimit: 1000,
9
  },
10
});
11
12
const scoped = bctrl.withSubaccount(subaccount.id);
13
const space = await scoped.spaces.create({ name: "Acme production" });

withSubaccount() returns a client whose requests carry that subaccount context. An organization-scoped key can also select a subaccount per request where the API supports it; a subaccount-scoped key cannot escape its own subaccount.

1
const active = await bctrl.subaccounts.list({ status: "active", q: "Acme" });
2
const withUsage = await bctrl.subaccounts.get(subaccount.id, { include: "usage" });
3
4
await bctrl.subaccounts.update(subaccount.id, {
5
  name: "Acme Inc",
6
  limits: { maxActiveRuns: 50 },
7
});
8
9
await bctrl.subaccounts.archive(subaccount.id);

Subaccount fields

SubaccountLimits contains maxSpaces, maxActiveRuns, and monthlyCreditLimit. A null limit means unlimited when updating limits.

Notification recipients

Notification recipients are destinations for human-in-the-loop requests. Create an email, SMS, or WhatsApp destination, then enable or disable it without deleting the resource.

1
const recipient = await bctrl.notificationRecipients.create({
2
  type: "email",
3
  value: "[email protected]",
4
  name: "Operations",
5
});
6
7
await bctrl.notificationRecipients.update(recipient.id, {
8
  enabled: false,
9
});
10
11
const enabled = await bctrl.notificationRecipients.list({ enabled: true });

Use E.164 phone numbers for sms and whatsapp, such as +15551234567.

Usage

Read organization usage from bctrl.usage. Read usage for every subaccount from bctrl.subaccounts.usage.

1
const organizationUsage = await bctrl.usage.get();
2
const subaccountUsage = await bctrl.subaccounts.usage.list();
3
4
console.log(organizationUsage.credits.available);
5
console.log(organizationUsage.isBlocked);
6
7
for (const usage of subaccountUsage.data) {
8
  console.log(
9
    usage.subaccountId,
10
    usage.credits.used,
11
    usage.credits.limit,
12
    usage.runs.active,
13
    usage.runs.limit,
14
    usage.spaces.used,
15
    usage.spaces.limit,
16
  );
17
}

Organization usage includes the current credit balance, monthly cycle, blocking state, and a breakdown across browser, proxy, AI, challenge solver, files, and notification credits.

Subaccount usage is a facts-only snapshot: credits.used/limit, runs.active/limit, and spaces.used/limit, plus the billing period and computation timestamp. A null limit means unlimited. Clients can derive remaining credits or a resource-specific limit notice from these values; the response does not include a subaccount-wide blocked state.

Account settings

Use account settings for organization-level branding. get() returns both the values you configured and the resolved values currently used by BCTRL.

1
const account = await bctrl.account.get();
2
console.log(account.id, account.name);
3
console.log(account.branding.config);
4
5
const updated = await bctrl.account.update({
6
  branding: {
7
    productName: "Acme Automation",
8
    accent: "#6D5EF5",
9
    showPoweredBy: false,
10
  },
11
});

Branding updates use a merge-patch shape: omitted fields stay unchanged, and null restores a field’s BCTRL default. Set dryRun: true in the second argument to validate and resolve a change without saving it.

1
await bctrl.account.update(
2
  { branding: { accent: "#6D5EF5" } },
3
  { dryRun: true },
4
);

Next

• Spaces — create isolated automation environments
• Runtimes — run automation inside a durable resource
• Tools — configure automation capabilities and human input
• Conversations — connect an agent to a Runtime