How integrations work

Ayven connects to two kinds of external service: the messaging platforms she lives in (Slack, Microsoft Teams) and the work tools she acts on (issue trackers, code). The two follow different shapes — messaging is event-driven and pushes to Ayven; work tools are read on demand and written through an approval gate. This page describes both shapes end to end.

None of this is a prerequisite. Ayven has a first-party native baseline — a native web-ticket provider that runs through the same operation pipeline with no external credentials (the "Native tickets & chat" row below) — so asks, loops, and missions work with nothing connected. Integrations extend that baseline into your own tools; they don't gate it.

The shape at a glance

Messaging platforms: event-driven, verified at the edge

Slack and Teams push events to Ayven; she never polls them. Both platforms require a fast acknowledgement, so a dedicated receiver acks each webhook immediately and hands the payload to the processing gateway as a separate request — the platform gets its answer in milliseconds while the real work (which can take a minute) runs with full resources.

Slack

1. Install. Adding Ayven to a workspace runs Slack's OAuth v2 flow. The install URL carries a single-use, short-lived state nonce; the callback verifies and consumes it before exchanging the code — a stolen callback can't be replayed.
2. Scopes. The install requests a fixed scope set: reading mentions and channel history, reading and writing DMs, posting messages, slash commands, and reading the workspace member list (app_mentions:read, channels:history, channels:read, chat:write, commands, im:history, im:read, im:write, team:read, users:read, users:read.email). No admin scopes, no file scopes.
3. Token custody. The workspace bot token is written to a backend-only connection store — it is deliberately kept out of any record that workspace members can read from the client.
4. Events. Ayven subscribes to mentions, direct messages, App Home opens, uninstalls, and token revocations. She checks each inbound request's HMAC-SHA256 signature and refuses one older than five minutes, and when the signing secret is missing she rejects every request.
5. Uninstall. An app_uninstalled or tokens_revoked event wipes the workspace's connection data, including any install-time token still parked from setup. The cleanup is idempotent — both events can fire and both are safe.

Microsoft Teams

1. Per-customer footprint is one value: the tenant ID. The bot's own credentials are app-level secrets held in the platform's secret manager — nothing customer-specific is a secret.
2. Every inbound activity is JWT-verified against Microsoft's published keys: signature, issuer, audience (the bot's app ID), and expiry, with the signing metadata cached and refreshed daily. Anyone who finds the messaging endpoint without a Microsoft-signed token gets a 401.
3. Outbound messages use short-lived Azure AD tokens acquired per tenant via client credentials, cached and refreshed before expiry so a token does not expire mid-conversation.

Work tools: connect, read live, write through the gate

Connecting a tracker

Connecting Jira, YouTrack, or Asana is a single verified exchange. The credentials you enter are checked live against the provider before anything is saved. Ayven then works inside what the token can reach:

• Accessible projects: Ayven works in the projects the token can see, and can create a new one once you approve it.
• Workspace vocabulary: Ayven reads each project's priorities, states and issue types from the tracker when she needs them, so she uses your own terms instead of guessing at them.
• Custom field identifiers — story points, sprint, and epic-link fields are resolved to their provider-specific IDs up front.
• Identity linking — after connect, workspace users are listed from the provider and matched to teammates by email, so "assign it to Dana" resolves to the right tracker account.

Invalid credentials fail the connect with the provider's answer; nothing is stored. Each agent holds at most one integration per provider, and disconnecting removes it.

The read path: live, on demand

When Ayven reports what's in your tracker, she is not reading a mirror. There is no background sync job and no shadow copy of your issues — each check is a live, scoped API query made at the moment the question is asked, using the integration's own credentials. Ayven sees only what the token can access. The agent's tracker tools — search, get ticket, get project, find user, workload, blocker chains — all dispatch through the same per-provider adapter, so a workspace with two trackers connected can be queried across both in one pass.

The write path: the approval gate

Ayven never mutates an external tool directly from a conversation. Writes follow a consent pipeline:

1. Plan. The agent submits a plan of one or more operations. Each operation carries a human-readable consent message and the agent's reasoning for proposing it.
2. Approve. Operations wait in a pending state until a person decides from Slack, Teams or the web app. The agent's owner can set some operation types to approve automatically. Approval can be routed: an operation can be assigned to a specific teammate for review. Rejections record who declined. A plan stays pending until a person decides it or cancels it.
3. Execute. On approval, the operation is dispatched to the delivery executor, which applies exactly that operation through the provider's REST API. The mutation surface is a closed set: create ticket, assign, update state, add comment, set parent, set sprint, add or remove a label, link tickets. An operation type outside this set is refused.
4. Report. The executor calls back with the result — the ticket key, URL, and state — and the operation record keeps the full trail: who approved, when, and the consent message that was approved. Artifacts created natively carry this origin trail on the artifact itself, so you can see later who approved it and why.

Inbound change events

Every tracker is pull-on-demand: no tracker pushes changes to Ayven, and she sees a ticket's change when she next reads it. Notion, Google Drive and SharePoint post document changes to an inbound webhook, and Ayven updates the search index from them.

GitHub

GitHub access is read-only and scoped per user, not per agent: each user connects their own personal access token, and code questions run against the repositories configured for the integration. The token is validated against GitHub before use; if validation fails, the query reports the failure instead of running with dead credentials.

What Ayven can and cannot touch

For what each integration does day to day, see Integrations and Project delivery. To reach Ayven from your own code, see the API reference.