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`	Send thumbs up/down style feedback for external replies
`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.

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.