Skip to main content
Use this path when you want to build around AcornOps rather than only operate the platform. Common examples include Slack, Telegram-style bots, incident workflow automation, custom dashboards, and internal tools that react to AcornOps run events.

​
Integration surfaces

Execution-engine and LLM-gateway runtime APIs are internal platform surfaces. Do not call them from external bots or customer integrations.

​
Auth model for integrations

The public control-plane API is session-based. Browser clients use the same SameSite=Lax session cookie as the management console. Mutating requests with a session cookie, plus password login and signup before a session exists, must echo the CSRF token in x-csrf-token. AcornOps v1 does not expose a public PAT or broad bot service-account credential for the control-plane API. Installed external integration clients authenticate with raw bearer tokens whose SHA-256 hashes are configured in EXTERNAL_INTEGRATION_CLIENTS_JSON. For v1 integrations, keep user actions attributable:
  • use webhooks for bot notifications and workflow triggers,
  • send users to the management console or an authenticated client flow for privileged actions,
  • call approval endpoints only as a real AcornOps user with the required workspace permission,
  • avoid shared bot-user decisions for write approvals.
Internal service tokens such as ORCH_SERVICE_TOKEN, EXECUTION_ENGINE_DISPATCH_TOKEN, and LLM_GATEWAY_ADMIN_TOKEN are platform credentials. External integration client bearer tokens are narrow adapter credentials, not public PATs. The built-in MCP bridge uses the run-scoped JWT minted for the active execution. AcornOps exposes a narrow external integration account-link contract for an external integration client. External integration client-side command handling, message copy, event handling, retries, and channel behavior belong outside AcornOps. The integration client can use:
  • POST /api/v1/auth/external-integrations/link with Authorization: Bearer <external-integration-client-token> and body { "externalUserId": "<external-user-id>", "externalDisplayName": "<optional-safe-name>" } to create a short-lived browser link.
  • POST /api/v1/auth/external-integrations/resolve with the same bearer token and body { "externalUserId": "<external-user-id>" } to resolve whether the external identity is linked or unlinked.
  • POST /api/v1/auth/external-integrations/revoke with the same bearer token and body { "externalUserId": "<external-user-id>" } to revoke the integration client’s durable link for that external user.
AcornOps returns a management-console linkUrl under /integrations/external/link. The user opens that URL within the token TTL, and the console shows the normal AcornOps login page when no browser session exists. After password or OIDC sign-in establishes a browser session, the console calls POST /api/v1/auth/external-integrations/link/preview to show safe pending-link metadata, then calls POST /api/v1/auth/external-integrations/link/complete only after the user explicitly approves. Signed-in users can list and unlink their own active external links through the user-owned external integration endpoints. External integration clients should not store browser cookies, OIDC tokens, raw link tokens, or an AcornOps user ID as authorization material. Browser login and link completion are AcornOps-owned session flows, not external integration APIs.

​
Bot adapter pattern

An external integration adapter usually follows this flow:
  1. Subscribe to the AcornOps webhook events the bot needs.
  2. Verify AcornOps-Signature using the subscription secret.
  3. Map the event to a channel, thread, incident, or user-visible card.
  4. For read-only context, link to the management console or fetch allowed public API data from a client flow that has an authenticated user session.
  5. For write approvals, render approve and reject controls only when the click can be tied back to a real AcornOps user.
  6. Submit approval decisions to POST /api/v1/runs/{runId}/approvals/{approvalId}/decision.
Approval decisions are intentionally not just webhook acknowledgements. The first recorded decision wins; conflicting later decisions return the current approval state.

​
Webhook events

Webhook delivery is best-effort and signed with HMAC-SHA256. Consumers should handle duplicates and out-of-order delivery. Each delivery includes:
  • AcornOps-Event-Id
  • AcornOps-Event-Type
  • AcornOps-Timestamp
  • AcornOps-Signature
Target-scoped events include targetId and targetType. Kubernetes events also include clusterId, which matches the Kubernetes target ID. The signature input is timestamp + "." + raw_json_body, encoded as v1=<hex>. Write approval integrations should handle:
  • run.tool_approval_requested.v1
  • run.tool_approval_decided.v1
MCP server integrations may also care about:
  • mcp.server.created.v1
  • mcp.server.updated.v1
  • mcp.server.deleted.v1
  • mcp.server.tested.v1
Use the API reference sidebar for webhook endpoint schemas and examples.

​
Tool and MCP integrations

There are two different integration directions: Remote MCP servers can receive non-secret publicHeaders. Credentials must use the secret-backed auth fields. Platform scope headers such as x-workspace-id, x-target-id, x-target-type, and x-run-id are reserved and added by the gateway. See MCP and tools for MCP setup and header policy.

​
Start here

Use this sequence for a new integration:
  1. Confirm the platform is deployed and reachable from your integration host.
  2. Decide whether the integration is webhook-driven, user-session driven, or both.
  3. Create a workspace webhook subscription for the required event types.
  4. Verify signatures before acting on payloads.
  5. Use API overview to confirm API boundaries, then use the API reference sidebar for endpoint schemas.
  6. Use MCP and tools only when AcornOps should call tools exposed by another system.