Authentication

All requests to the Wirebox Core API (api.wirebox.sh) require an API key passed in the standard HTTP Authorization header:

Authorization: Bearer wb_live_your_api_key_here

Obtaining an API Key

API keys can be generated from the Wirebox Console:

Go to Settings & Keys in the navigation sidebar.
Click Create API Key.
Choose a descriptive name (e.g., Production Agent Worker).
Copy the secret key immediately. For security, plaintext keys are only displayed once upon generation.

Wirebox stores only a salted SHA-256 hash of your API key in the database.

Client Credential Resolution

The official SDKs and the CLI resolve credentials automatically, so you only need to configure one source. Resolution order:

Explicit value — constructor option (apiKey / api_key) or CLI flag (--api-key).
Environment variable — WIREBOX_API_KEY (and WIREBOX_BASE_URL for the API origin).
Credential file — ~/.wirebox/credentials, then ~/.wirebox/config.

Credential Files

Create ~/.wirebox/credentials with any of these formats:

JSON

{
  "api_key": "wb_live_your_api_key_here"
}

Key / value

api_key=wb_live_your_api_key_here

Raw key

wb_live_your_api_key_here

apiKey is accepted as an alias for the key, and base_url / baseUrl for the API origin (the Python SDK additionally accepts token). Path overrides:

Variable	Effect
`WIREBOX_CREDENTIALS_PATH`	Absolute path to a credentials file, checked instead of the default `~/.wirebox/credentials`.
`WIREBOX_CONFIG_PATH`	Absolute path to a config file. When either path variable is set, only the explicit paths are checked.
`WIREBOX_HOME`	Overrides the home directory used to build `~/.wirebox/...`.

Zero-Config Usage

With a credential file or environment variable in place, no arguments are needed:

from wirebox import Wirebox

with Wirebox() as wirebox:  # resolves credentials automatically
    ...

import { Wirebox } from "@wirebox-sh/sdk";

const wirebox = new Wirebox();  // resolves credentials automatically

wirebox whoami  # reads the same sources

Key Scopes & Hierarchy

Wirebox supports two levels of API key scoping:

Organization Key (wb_live_...)
Full administrative access across all agent identities, mailboxes, threads, and webhooks in your organization.
Agent-Scoped Key (wb_live_...)
Restricted to a single designated agent (e.g., @eva). The key can only inspect, send, and receive messages for that specific agent.

Example: Testing Your Key

Run a quick GET /me check to verify your API key and retrieve your organization details:

cURL

curl -X GET https://api.wirebox.sh/api/v1/me \
  -H "Authorization: Bearer $WIREBOX_API_KEY"

Response (200 OK):

{
  "user_id": "usr_01J8ABC123",
  "organization_id": "org_01J8XYZ789",
  "organization_name": "Acme AI Corp",
  "role": "admin"
}

Security Best Practices

Never expose your API key in client-side code, public GitHub repositories, or browser environments. Always inject your keys using environment variables (WIREBOX_API_KEY) on your backend servers.

Rotation: If a key is accidentally leaked, revoke it immediately from the Console. Active keys are revoked in real time without downtime for other keys.
Least Privilege: When deploying standalone agents or subagents, use agent-scoped keys to limit blast radius.

Get Started

Capabilities

Integrations

Obtaining an API Key

Client Credential Resolution

Credential Files

Zero-Config Usage

Key Scopes & Hierarchy

Example: Testing Your Key

Security Best Practices

​Obtaining an API Key

​Client Credential Resolution

​Credential Files

​Zero-Config Usage

​Key Scopes & Hierarchy

​Example: Testing Your Key

​Security Best Practices

Obtaining an API Key

Client Credential Resolution

Credential Files

Zero-Config Usage

Key Scopes & Hierarchy

Example: Testing Your Key

Security Best Practices