Skip to main content

​
Connect Slack, Gmail, and event sources

Agent workflows read from and propose writes to connected systems through tenant-owned connections. Slack and Gmail authenticate through Nango. External systems that trigger workflows use signed event credentials issued from the Studio. Open the Connections tab from the Agents area in the main navigation.

​
Slack and Gmail through Nango

Slack and Gmail connections are managed by Nango and belong to the tenant. Each connection is separate: reading Slack channels does not grant permission to post, and reading Gmail threads does not grant permission to send.

​
Add a connection

  1. In Connections, choose the provider card (Slack or Gmail).
  2. Select Connect. Control opens a Nango-hosted consent screen.
  3. Sign in with the account you want the tenant’s workflows to use and grant the requested scopes.
  4. When the handoff completes, the connection appears with status Active.
The account used for the connection should be one that finance controls, not a personal account. Provider consent applies at the tenant level and is subject to revocation.

​
Use a connection in a workflow

In the Builder, enable a Slack or Gmail tool. The tool card exposes:
  • Connection. The specific Slack or Gmail connection the tool should use.
  • Approval mode. How the tool proposes writes (currently, external writes always require approval).
  • Fixed destination. For posting tools, the exact channel, address, or draft target that the agent may target. Fixed destinations are locked into every proposal and cannot be changed at approval time.
Tools that only read data do not require a fixed destination.

​
Reconnect or revoke

Reconnecting is handled by Nango. If a connection’s tokens expire or scopes change, the connection card shows a Reconnect action that restarts the Nango handoff. Revoking a connection detaches it from every workflow that used it. Workflows keep working, but tools bound to the revoked connection will fail until you attach a new one.

​
Signed event credentials

Signed event credentials let external systems trigger workflows through the /agent-events endpoint. Each credential is tenant-bound, one-time visible, and independently revocable. Creating and revoking credentials requires an organization administrator. Any tenant member can list the credentials that already exist.

​
Create a credential

  1. In Connections, go to Signed event credentials.
  2. Enter a name that describes the source system, for example Production event source.
  3. Select Create.
Control returns the credential token exactly once. The token has the form:
Store the secret in the sending system’s secret manager immediately. Control only keeps the hash of the secret and cannot show it again. The prefix is retained and visible in the Connections view so you can identify which credential is which.

​
Use a credential

Every signed request to /agent-events supplies three headers:
  • Authorization: Bearer cae.<prefix>.<secret>
  • X-Control-Event-Timestamp: <unix seconds>
  • X-Control-Event-Signature: <lowercase hex HMAC-SHA256(secret, "<timestamp>." + raw body)>
The raw request body is a JSON object with eventType, dedupeKey, payload, and an optional connectionId. Bodies larger than 64 KiB are rejected. Requests with timestamps more than five minutes off the server clock are rejected. See Trigger workflows for a full example and workflow-side configuration.

​
Revoke a credential

Revoking a credential is immediate.
  1. In Signed event credentials, find the credential by its prefix or name.
  2. Select Revoke.
Revoked credentials cannot authenticate new events. Historical occurrences, runs, and audit entries created while the credential was active are retained. Rotate a credential by creating a new one, updating the sending system to use the new token, and then revoking the old one.

​
Provider payload boundaries

The Studio enforces a few boundaries that keep external actions safe:
  • Slack and Gmail reads use Nango connections that are separate from the credentials used to write.
  • Writes never happen without an approved proposal. Fixed destinations, when configured on the tool, are recorded in the proposal and cannot be edited by the approver.
  • Executed proposals record the provider’s receipt (message ID or draft ID). If Control loses visibility into delivery, the Approvals view lets a reviewer reconcile with the provider directly. See Review runs and approvals.