Authentication

What This Does

Tool connector tokens let an outside app call Bombyx on behalf of one organization.

Each token belongs to:

One organization
One connector
A set of allowed capabilities

Before You Start

A Bombyx organization owner or admin must create the connector in the app.

In Bombyx:

Open the app.
Go to Tool connectors.
Create a connector.
Pick only the capabilities the integration needs.
Create a token.
Copy the token right away.

The token is shown once. Bombyx stores only a hash after that.

Bearer Token

Send the token in the Authorization header:

curl https://bombyxlabs.com/app/api/tool-connectors/v1/status \
  -H "Authorization: Bearer btx_your_token_here"

Successful response:

{
  "ok": true,
  "organization": {
    "id": 42,
    "name": "Example Company"
  },
  "brain_tool": {
    "id": 7,
    "name": "Support inbox connector",
    "type": "external_tool",
    "access_mode": "internal_default",
    "capabilities": ["assistant_reply", "assistant_feedback"],
    "client_key": "external_ab12cd34"
  }
}

Capabilities

Capabilities are the actions the token is allowed to take.

Capability	Allows
`assistant_reply`	Draft suggested replies with the External Assistant API
`assistant_feedback`	Report whether an external reply was accepted, corrected, or rejected
`assistant_tool:<tool-key>`	Allow the external assistant workflow to call one exact assistant tool
`memory_search`	Search and read organization memory available to the connector
`memory_save`	Save private or internal tool memory
`memory_propose`	Propose reviewed updates to organization memory
`internal_code_read`	Allows internal/code memory when the connector policy permits it

If a token is missing a needed capability, Bombyx returns 403.

Capabilities do not bypass organization boundaries or source policy. Search and assistant routes return only evidence available to the token’s organization and connector policy.

Assistant tool capabilities are exact. assistant_reply allows reply drafting but does not expose every configured assistant tool. Add only the specific assistant_tool:<tool-key> capabilities the integration requires.

Token Safety

Treat btx_... tokens like passwords.

Do not commit them.
Do not put them in screenshots.
Do not paste them into public chats.
Store them in your app’s secret manager.
Rotate the token if it leaves your control.

Common Mistakes

Using https://bombyxlabs.com/api/tool-connectors/v1 in production. Use /app/api/tool-connectors/v1.
Losing the token after creation. It cannot be shown again.
Creating one token with every capability. Use the fewest capabilities that work.