AllternitBus API - Allternit Docs

Overview

The AllternitBus API provides the runtime surface agents use to send and receive messages, store encrypted secrets, resolve connector credentials, and manage identity channels such as email, phone, and wallet addresses. All authenticated routes are mounted under /api/v1 and require a valid bearer token via the platform auth middleware. The public inbound webhook is mounted at /webhooks/photon and is called server-to-server by Photon.codes.

This namespace is served by the Allternit API data-plane node (http://127.0.0.1:8013 on the same machine, or your paired or provisioned node). The hosted Cloud API at https://api.allternit.com does not route it; it relays only agent sessions, canvases, office and beta research/sessions. See Cloud API.

Base URL

Authenticated surface:

http://127.0.0.1:8013/api/v1

Public webhook surface:

http://127.0.0.1:8013/webhooks/photon

For local development:

http://127.0.0.1:8013/api/v1
http://127.0.0.1:8013/webhooks/photon

Authentication

All authenticated routes require a valid bearer token in the Authorization header. The inbound Photon webhook is authenticated server-to-server by Photon.codes and does not carry a Clerk session. See Authentication for details.

Endpoints

Method	Path	Description
`POST`	`/api/v1/photon/agents/:agent_id/inbox`	Deliver a message to an agent inbox.
`GET`	`/api/v1/photon/agents/:agent_id/inbox`	List messages in an agent inbox.
`PUT`	`/api/v1/agents/:agent_id/secrets/:key`	Set or update an encrypted agent secret.
`POST`	`/api/v1/agents/:agent_id/secrets/resolve`	Resolve one or more agent secrets by reference.
`POST`	`/api/v1/agents/:agent_id/connectors/resolve`	Resolve connector credentials for an agent.
`GET`	`/api/v1/agents/:agent_id/identity`	Get an agent’s identity channels.
`POST`	`/api/v1/agents/:agent_id/identity/email`	Provision an email address for an agent.
`DELETE`	`/api/v1/agents/:agent_id/identity/email`	Give up the agent’s address so a new one can be provisioned.
`POST`	`/api/v1/agents/:agent_id/identity/phone`	Provision a phone number for an agent.
`POST`	`/api/v1/photon/sessions/:session_id/bridge`	Bridge a session to another surface.
`POST`	`/webhooks/photon`	Public webhook for inbound Photon messages.

Message inbox

Send a message

POST /api/v1/photon/agents/:agent_id/inbox

Delivers a message to the agent’s inbox. The route path is kept for backward compatibility with the Photon.codes integration.

Request body

Field	Type	Required	Description
`from`	string	Yes	Sender identifier.
`content`	string	Yes	Message body.
`surface`	string	No	Surface or channel the message arrived on.

Example request

curl -X POST http://127.0.0.1:8013/api/v1/photon/agents/agent_018f3a7c.../inbox \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "user_2d9e...",
    "content": "Please summarize the latest report.",
    "surface": "chat"
  }'

Example response

{
  "id": "msg_7a1b...",
  "status": "delivered"
}

List inbox messages

GET /api/v1/photon/agents/:agent_id/inbox

Returns messages for the agent, newest first.

Query parameters

Parameter	Type	Description
`since`	string	ISO 8601 timestamp; only return messages created after this time.
`limit`	integer	Maximum number of messages (default `100`, max `500`).

Example request

curl -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:8013/api/v1/photon/agents/agent_018f3a7c.../inbox?limit=10"

Example response

{
  "agent_id": "agent_018f3a7c...",
  "messages": [
    {
      "id": "msg_7a1b...",
      "from": "user_2d9e...",
      "to": "agent_018f3a7c...",
      "content": "Please summarize the latest report.",
      "surface": "chat",
      "created_at": "2026-08-13T14:22:00Z"
    }
  ]
}

Inbound webhook

Receive an inbound message

POST /webhooks/photon

Public webhook called by Photon.codes when an inbound SMS or message arrives. The payload is routed to the agent whose identity channel matches the to phone number. No bearer token is required.

Request body

Field	Type	Required	Description
`from`	string	Yes	Originating address.
`to`	string	Yes	Destination phone number.
`body`	string	Yes	Message body.
`channel`	string	Yes	Channel the message arrived on.
`message_id`	string	Yes	External message identifier.

Example request

curl -X POST http://127.0.0.1:8013/webhooks/photon \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "body": "Hello, can you help me?",
    "channel": "sms",
    "message_id": "photon_msg_9c1d..."
  }'

Example response

{
  "status": "accepted"
}

Secrets

Set a secret

PUT /api/v1/agents/:agent_id/secrets/:key

Stores an encrypted secret value for the agent. Values are sealed at rest via token_crypto. If a secret with the same key already exists, it is overwritten.

Request body

Field	Type	Required	Description
`value`	string	Yes	Secret value to encrypt and store.
`name`	string	No	Human-readable name; defaults to `:key`.
`description`	string	No	Optional description.
`required`	boolean	No	Whether the secret is required for agent operation.

Example request

curl -X PUT http://127.0.0.1:8013/api/v1/agents/agent_018f3a7c.../secrets/PHOTON_API_KEY \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "sk_live_...",
    "name": "Photon API Key",
    "description": "Project secret for outbound messaging.",
    "required": true
  }'

Example response

204 No Content

Resolve secrets

POST /api/v1/agents/:agent_id/secrets/resolve

Decrypts and returns values for the requested secret references. Required secrets that are missing or cannot be decrypted are reported in missing and errors.

Request body

Field	Type	Required	Description
`refs`	array	Yes	List of secret references to resolve.

Each reference:

Field	Type	Required	Description
`name`	string	Yes	Human-readable name.
`key`	string	Yes	Stored secret key.
`required`	boolean	No	Whether absence is reported as missing.

Example request

curl -X POST http://127.0.0.1:8013/api/v1/agents/agent_018f3a7c.../secrets/resolve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "refs": [
      { "name": "Photon API Key", "key": "PHOTON_API_KEY", "required": true }
    ]
  }'

Example response

{
  "secrets": [
    {
      "key": "PHOTON_API_KEY",
      "value": "sk_live_...",
      "source": "vault"
    }
  ],
  "missing": [],
  "errors": []
}

Connectors

Resolve connector credentials

POST /api/v1/agents/:agent_id/connectors/resolve

Resolves live credentials for the requested connector bindings. The route first looks up a connected connector_connections row for the caller, then falls back to legacy allternit_vault_credentials that belong to the agent and user.

Request body

Field	Type	Required	Description
`bindings`	array	Yes	Connector bindings to resolve.

Each binding:

Field	Type	Required	Description
`connector_id`	string	Yes	Connector identifier.
`provider`	string	Yes	Provider slug.
`label`	string	No	Display label used in missing-credential messages.
`capabilities`	array	No	Capability strings.
`autonomous`	boolean	No	Whether the connector may act autonomously.
`allowed_actions`	array	No	Action allow-list.

Example request

curl -X POST http://127.0.0.1:8013/api/v1/agents/agent_018f3a7c.../connectors/resolve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bindings": [
      {
        "connector_id": "conn_4d5e...",
        "provider": "photon",
        "label": "Photon SMS",
        "required": true
      }
    ]
  }'

Example response

{
  "credentials": [
    {
      "connector_id": "conn_4d5e...",
      "provider": "photon",
      "key": "PHOTON_ACCESS_TOKEN",
      "value": "sk_live_...",
      "source": "connector_connections"
    }
  ],
  "missing": [],
  "errors": []
}

Identity channels

Get identity channels

GET /api/v1/agents/:agent_id/identity

Returns the agent’s bound identity channels: email, phone, and wallet. Channels that have not been provisioned are returned as null.

Example request

curl -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8013/api/v1/agents/agent_018f3a7c.../identity

Example response

{
  "agent_id": "agent_018f3a7c...",
  "email": {
    "address": "[email protected]",
    "provider": "custom",
    "sendEnabled": true,
    "receiveEnabled": true
  },
  "phone": {
    "number": "+15559876543",
    "provider": "vapi",
    "voiceEnabled": true,
    "smsEnabled": true
  },
  "wallet": null
}

Provision email

POST /api/v1/agents/:agent_id/identity/email

Provisions an email address for the agent on ALLTERNIT_BOT_EMAIL_DOMAIN (default bots.allternit.com): through Allternit’s cloud on a signed-in computer, or directly when the runtime has Allternit Mail’s admin key. See Agent email rail. When the mailflare agent-email rail is configured (ALLTERNIT_MAILFLARE_URL + ALLTERNIT_MAILFLARE_ADMIN_KEY), this creates a real mailbox on the mailflare worker, mints a mailbox-scoped send/read API key, seals it server-side, and stores the channel with provider "mailflare". The agent can then genuinely receive and (subject to approval) send internet email. When mailflare is not configured, the endpoint falls back to minting an address record only (provider "commrails", a stored value) with no send/receive transport. Provisioning is idempotent: re-provisioning an agent returns its existing channel. A platform address (provider mailflare) is owned by the server: a PATCH /api/v1/agents/:id that sends a different identityChannels.email.address keeps the stored one. To change it, release it and provision again (below). Switching the bot to its own mail account (provider other than mailflare / commrails) still saves the new address. To put the bot on a verified company domain, send { "localPart": "support", "domain": "acme.com" } (see Company domains). A domain whose records haven’t all checked returns 409 domain_not_verified; a bot that already has an address elsewhere returns 409 email_address_exists (release it first). The part before the @ comes from the optional body { "localPart": "ledger-bot" }: 3-40 lowercase letters, numbers and single hyphens (invalid values return 400 invalid_local_part; role names such as postmaster return 400 reserved_local_part). A requested name that is already taken returns 409 email_local_part_taken. Without localPart, the address is a slug of the bot’s name (ledger-bot), with -2, -3 and so on added only when that address is taken. The mailbox’s display name, which becomes the From name on outbound mail, is the bot’s name.

Example request

curl -X POST http://127.0.0.1:8013/api/v1/agents/agent_018f3a7c.../identity/email \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"localPart": "ledger-bot"}'

Example response

{
  "address": "[email protected]",
  "provider": "mailflare"
}

Change an agent’s address

DELETE /api/v1/agents/:agent_id/identity/email

Removes the agent’s mailbox (on a cloud-provisioned runtime, cloud-api also removes its key, its webhook and the relay route), then clears the address and the mailbox credentials from the agent. Reply settings (replyMode, replyAllowlist) stay. Mail sent to the old address stops arriving. Follow it with POST …/identity/email {"localPart": "<new name>"}. If the mailbox can’t be removed, the call returns 502 mailbox_not_removed and the agent keeps its address. The app’s email wizard and the bot’s Identity settings do both steps; when the new name is taken they provision the default address again and say which address the bot is on.

{ "released": true }

Agent email rail

Real inbound/outbound email for agents, backed by a per-installation mailflare worker (see services/mailflare/). Inbound mail arrives as an HMAC-signed webhook and is bridged into the agent’s Factory mail threads; outbound mail is held for human approval before it is sent.

Two ways a runtime gets bot email

Mode	Who creates the mailbox	Keys on the runtime
Cloud-provisioned (default for every signed-in computer)	cloud-api, `POST /api/v1/runtime-devices/me/bot-email/mailboxes {agentId, localPart, displayName?}` with the runtime’s device credential. The cloud creates an `email` relay route to that runtime, the mailbox on `bots.allternit.com` (a taken name gets `-2`, `-3`…), a send+read key scoped to that mailbox, and a `message.inbound` webhook scoped to that mailbox only, and returns `{address, mailboxId, apiKey, webhookSecret, mailUrl}` once. `DELETE …/mailboxes/:mailbox_id` removes all of it.	Only the bot’s own sealed key and its webhook secret. Never the admin key.
Admin (an operator runtime)	The runtime itself, with `ALLTERNIT_MAILFLARE_URL` + `ALLTERNIT_MAILFLARE_ADMIN_KEY`.	The admin key; one runtime-wide `ALLTERNIT_MAILFLARE_WEBHOOK_SECRET`.

Inbound mail is verified with the receiving mailbox’s own secret (cloud-provisioned) or the runtime-wide one (admin), before anything in the body is trusted; the bot is found by the event’s mailboxId, then the delivered-to address, then to. A cloud-provisioned bot’s direct replies (auto, auto_known) are sent with its own key and approved by the runtime itself once its review and autonomy rules allow them. A mailbox’s mail is never delivered to another runtime: each webhook is scoped to one mailbox. ALLTERNIT_BOT_EMAIL_BROKERED=0 turns the cloud mode off. cloud-api answers 503 bot_email_not_configured until ALLTERNIT_MAILFLARE_URL and ALLTERNIT_MAILFLARE_ADMIN_KEY are set on it.

Company domains

Bots can use a customer’s own domain ([email protected]) instead of bots.allternit.com. The domain’s mail runs through Allternit’s mail host, mx.allternit.com (Postfix plus services/mail-relay), not through Cloudflare: the customer’s domain never needs to be in Allternit’s Cloudflare account.

Call (runtime, signed in)	What it does
`PUT /api/v1/agent-email/domains/:domain`	Adds the domain for the signed-in account and answers `{domain, state, records}`: four records to add where the domain’s DNS is managed.
`GET /api/v1/agent-email/domains[?domain=acme.com]`	Checks each record live at public DNS and answers `{domains: [{domain, state, records}]}`; `state` turns `verified` when all four are found.
`DELETE /api/v1/agent-email/domains/:domain`	Removes a domain no bot uses (`409 domain_in_use` names the address that still does).

The records (each comes back with ok: true | false after a check):

Type	Host	Value	Why
MX	`acme.com`	`10 mx.allternit.com`	Receives the bots’ mail
TXT	`acme.com`	`v=spf1 a:mx.allternit.com ~all`	Allows Allternit to send as the domain (merge into an existing SPF record; a domain may have only one)
TXT	`allternit._domainkey.acme.com`	`v=DKIM1; k=rsa; p=…`	Signs the bots’ mail with the domain’s own key
TXT	`_allternit.acme.com`	`allternit-verify=…`	Proves ownership

Pointing a domain’s MX at mx.allternit.com sends all of that domain’s mail to the bots, so use a domain or subdomain (bots.acme.com) that doesn’t already receive mail elsewhere. A domain belongs to one Allternit account (409 domain_taken for anyone else); allternit.com and its subdomains are refused. On a signed-in computer the runtime calls cloud-api (PUT/GET/DELETE /api/v1/runtime-devices/me/bot-email/domains[/:domain], device credential), which records ownership in bot_email_domains (migration 062, applied by hand to prod) and calls Allternit Mail’s /api/v1/relay/domains/:host with the admin key. A runtime with the admin key calls that route itself. Allternit Mail (D1 migration 0012_relay_domains.sql, column domains.transport = 'relay') asks the relay to make the domain’s DKIM key and check DNS, marks the domain active once it verifies, and from then on:

Inbound: Postfix on mx.allternit.com accepts mail only for verified domains and existing bot mailboxes (live socketmap lookups to the relay, which asks the worker’s GET /api/v1/relay/recipient), and the relay posts it to the worker’s POST /api/v1/relay/inbound. From there it is the same path as any bot mail.
Outbound: mail from a relay domain goes to the relay’s POST /relay/send, which signs it with the domain’s DKIM key and queues it in Postfix (retries for up to two days).

Worker env: MAIL_RELAY_URL (https://mx.allternit.com/relay) and MAIL_RELAY_SECRET (32+ characters, the same value as the relay’s RELAY_SECRET). Without them, adding a domain answers 503 custom_domains_unavailable. The relay’s install script is services/mail-relay/deploy/install.sh.

Send email (approval-gated)

POST /api/v1/agent-email/send

Field	Type	Required	Description
`agent_id`	string	Yes	Owning agent. Must have a mailflare email channel with send enabled.
`to`	string	Yes	Recipient address.
`subject`	string	Yes	Subject line.
`text`	string	One of text/html	Plain-text body.
`html`	string	One of text/html	HTML body.

The message is not sent immediately. It is recorded as pending_approval and a review is requested on a Factory mail thread (mail:email-out-<id>). A human approves or rejects via POST /api/factory/mail/decide with { "thread": "<thread_id>", "approve": true|false }; approving triggers the actual send and writes a receipt with the provider message id. The decide response includes an email object for email threads.

{
  "status": "pending_approval",
  "thread": "mail:email-out-9f1c...",
  "outbound_id": "9f1c..."
}

Email rail status

GET /api/v1/agent-email/status

Reports whether the mailflare rail is configured, the agent email domain, and whether the worker is reachable. Use this to diagnose installations.

Inbound webhook (server-to-server)

POST /api/v1/agent-email/inbound

Public route called by the mailflare worker, authenticated by an X-Email-Platform-Signature HMAC-SHA256 header against ALLTERNIT_MAILFLARE_WEBHOOK_SECRET. message.inbound events are stored and bridged into the receiving agent’s Factory mail thread (mail:email-in-<agent>). Unknown recipients return 202 and are logged.

Provision phone

POST /api/v1/agents/:agent_id/identity/phone

Assigns a phone number to the agent from the comma-separated pool in ALLTERNIT_BOT_PHONE_POOL. The first number not already assigned to another agent is chosen.

Example request

curl -X POST http://127.0.0.1:8013/api/v1/agents/agent_018f3a7c.../identity/phone \
  -H "Authorization: Bearer $TOKEN"

Example response

{
  "number": "+15559876543",
  "provider": "vapi"
}

Cross-surface bridge

Bridge a session

POST /api/v1/photon/sessions/:session_id/bridge

Requests a cross-surface bridge for a session. The route path is kept for backward compatibility. The payload is echoed back with a bridged status.

Request body

Field	Type	Required	Description
`target_surface`	string	Yes	Surface to bridge the session to.
`payload`	object	Yes	Opaque bridge payload.

Example request

curl -X POST http://127.0.0.1:8013/api/v1/photon/sessions/sess_9c1d.../bridge \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_surface": "cowork",
    "payload": { "thread_id": "thread_3f8a..." }
  }'

Example response

{
  "session_id": "sess_9c1d...",
  "target_surface": "cowork",
  "status": "bridged",
  "payload": { "thread_id": "thread_3f8a..." }
}

Error codes

Status	Code	Meaning
`200 OK`	—	Request succeeded.
`202 Accepted`	—	Message or bridge accepted for processing.
`204 No Content`	—	Secret stored successfully.
`400 Bad Request`	`invalid_key`	Secret key cannot be empty.
`400 Bad Request`	`empty_value`	Secret value cannot be empty.
`401 Unauthorized`	—	Missing or invalid bearer token.
`403 Forbidden`	`forbidden`	Agent does not belong to the caller.
`404 Not Found`	`not_found`	Agent not found.
`409 Conflict`	`phone_pool_exhausted`	No phone numbers left in the configured pool.
`409 Conflict`	`email_not_provisioned`	Agent has no mailflare email channel; provision one first.
`403 Forbidden`	`email_send_disabled`	Outbound email is disabled for this agent.
`500 Internal Server Error`	`internal_error`	Unexpected server error.
`501 Not Implemented`	`email_domain_not_configured`	Allternit Mail isn’t configured and `ALLTERNIT_BOT_EMAIL_DOMAIN` is not set.
`501 Not Implemented`	`mailflare_not_configured`	`ALLTERNIT_MAILFLARE_URL` / `ALLTERNIT_MAILFLARE_ADMIN_KEY` are not set.
`501 Not Implemented`	`phone_pool_not_configured`	`ALLTERNIT_BOT_PHONE_POOL` is not set.
`501 Not Implemented`	`phone_pool_empty`	`ALLTERNIT_BOT_PHONE_POOL` is empty.

​Overview

​Base URL

​Authentication

​Endpoints

​Message inbox

​Send a message

​Request body

​Example request

​Example response

​List inbox messages

​Query parameters

​Example request

​Example response

​Inbound webhook

​Receive an inbound message

​Request body

​Example request

​Example response

​Secrets

​Set a secret

​Request body

​Example request

​Example response

​Resolve secrets

​Request body

​Example request

​Example response

​Connectors

​Resolve connector credentials

​Request body

​Example request

​Example response

​Identity channels

​Get identity channels

​Example request

​Example response

​Provision email

​Example request

​Example response

​Change an agent’s address

​Agent email rail

​Two ways a runtime gets bot email

​Company domains

​Send email (approval-gated)

​Email rail status

​Inbound webhook (server-to-server)

​Provision phone

​Example request

​Example response

​Cross-surface bridge

​Bridge a session

​Request body

​Example request

​Example response

​Error codes

​Related pages

Overview

Base URL

Authentication

Endpoints

Message inbox

Send a message

Request body

Example request

Example response

List inbox messages

Query parameters

Example request

Example response

Inbound webhook

Receive an inbound message

Request body

Example request

Example response

Secrets

Set a secret

Request body

Example request

Example response

Resolve secrets

Request body

Example request

Example response

Connectors

Resolve connector credentials

Request body

Example request

Example response

Identity channels

Get identity channels

Example request

Example response

Provision email

Example request

Example response

Change an agent’s address

Agent email rail

Two ways a runtime gets bot email

Company domains

Send email (approval-gated)

Email rail status

Inbound webhook (server-to-server)

Provision phone

Example request

Example response

Cross-surface bridge

Bridge a session

Request body

Example request

Example response

Error codes

Related pages