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 only 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 roster (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. Every inbound request is HMAC-SHA256 signature-verified with a five-minute replay window, and verification fails closed: if the signing secret is missing, requests are rejected, not waved through.
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 mid-conversation requests never race a dying token.

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 — the same call discovers what the token can actually reach:

• Accessible projects — the projects this token can see become the integration's project list; Ayven does not operate outside it.
• Workspace vocabulary — the tracker's real priorities, states, and issue types are captured at connect time, so the agent speaks your workflow's language instead of guessing at it.
• 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. What the token can't see, Ayven can't see. 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, from Teams, or from the web app. Approval can be routed: an operation can be assigned to a specific teammate for review, which suspends the plan's expiry while a human owns the decision. Rejections record who declined; unattended plans expire rather than lingering.
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, answering "why does this exist" permanently.

Inbound change events

The tracker path above is pull-on-demand. YouTrack additionally supports push: a user-installed workflow in your YouTrack instance posts issue changes to a per-agent webhook URL, authenticated with a token header and run through dedup and debounce before processing — so a burst of edits becomes one signal. Notion and Google Drive document sources use the same inbound-webhook pattern for change notification. Jira and Asana are currently pull-only.

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.