Connections

Available now. The connection layer is a first-party Vetta capability (“Passport”).

A connection authorizes an identity to act inside a third-party app — helpdesks, issue trackers, email, chat, CRMs, docs, and over a thousand more — over OAuth or a scoped API key. Once connected, the agent reaches the app’s tools through Vetta’s connection tooling and never handles the raw credential; Vetta stores it, injects it at call time, and refreshes managed OAuth tokens server-side. There is no list of supported apps to check against. The catalogue is read live, so the first step of any setup is a search:

CLI

vetta identity connections apps --search helpdesk
# -> zendesk · Zendesk · managed_oauth/oauth · 12 operations

Two objects

Every connection is built from two objects. Keeping them separate is what lets one authorized app serve many identities under different policies.

Auth config — how an app authenticates. It pins the auth method (managed OAuth, your own OAuth app, or an API key), the scopes, any custom app credentials, and — the part that matters most — the operations a connection may call. Anything not pinned does not exist to the agent. One auth config per app is typically shared across the org.
Connected account — a per-identity instance of that auth config: the actual authorization for one identity, with its own lifecycle, status, and token. This is what a connection_call runs against.

auth config (connector: "zendesk", scopes, pinned tools)
   └── connected account  → identity "ava"    (active)
   └── connected account  → identity "sales"  (initiated)

Connecting

An end user authorizes through a hosted Connect Link. There is no non-interactive path: OAuth needs the user’s consent, and an API-key connector asks for the key on the same hosted form so it never travels through a Vetta request body. Either way the result is a connected account bound to one identity.

Find the app

Search the catalogue, then read the one you want whole — it tells you which auth methods work, the operations pinned by default, and anything connecting will still ask for.

CLI

vetta identity connections apps --search helpdesk
vetta identity connections app zendesk

Create the auth config (once per app)

Managed OAuth needs no credentials of your own; bring a custom OAuth app or API key when you need it. Pin the operations with --tool to narrow the surface below the app’s default set.

CLI

vetta identity connections config-add --connector zendesk --auth managed_oauth

Start a connection

Initiate a connected account for an identity. Vetta returns a hosted Connect Link the end user opens to authorize — see the caveat on connect_link below about whose domain serves it.

CLI

vetta identity connect --identity idn_... --auth-config ac_... --field subdomain=acme
# -> the hosted authorization page for this connected account

cURL

curl https://api.vetta.sh/v1/connections \
  -H "Authorization: Bearer $VETTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "identity": "idn_...", "auth_config_id": "ac_...", "fields": { "subdomain": "acme" } }'
# -> { "id": "ca_8f2c", "status": "initiated",
#      "connect_link": "https://…", "connect_link_expires_at": "…" }

Authorize

The user completes OAuth (or submits the API key) at the Connect Link and is returned to your dashboard, which reads the account and says what happened. The connected account moves from initiated to active on its own.

Poll, do not wait for a webhook. GET /v1/connections/{id} reconciles against the provider on read, so re-reading the connection is the refresh. There is no connection.* webhook yet, so a program that needs to know when a person finished authorizing polls this route.

Use it

The identity’s agent lists the tools available on the connected account and invokes them.

CLI

vetta identity connections list --identity ava

The agent can start this itself

The four steps above are the operator’s path. An agent has the same flow as three tools, offered to every session whose agent has an identity — so “connect our Zendesk” is something you can say to the agent rather than something you have to go and do for it.

Tool	What it does
`connections.search`	Searches the catalogue by name, category or what an app does, and returns each app’s id. There are over a thousand apps and the list changes without a release of ours, so there is nothing to memorize — the agent searches.
`connections.connect`	Starts an authorization for this agent’s identity and returns the Connect Link. The agent hands that link to the person; it cannot authorize on their behalf. Reuses the org’s existing auth config for the app rather than creating a second.
`connections.status`	Reads whether the person finished. `active` means the account’s tools are offered from the next turn on.

The consent screen is the approval. connections.connect produces a URL and nothing else: no credential exists and no tool is gained until a human opens it and authorizes at the third party. If you want a gate earlier than that, these register as ordinary tool names, so "connections.connect": { "permission": "ask" } in the agent’s tools.configs parks the session for approval like any other tool.

Tools arrive on the next turn. The session resolves its connected accounts when a turn starts, so an account authorized mid-conversation is usable on the turn after it reads active — which is what connections.status is for.

Lifecycle

A connected account moves through a small set of states. Managed OAuth tokens are refreshed server-side, so an active account keeps working without your involvement.

initiated

Connect Link issued; awaiting the user’s authorization.

active

Authorized and usable. Tokens refresh automatically in the background.

failed

Authorization or a refresh failed. status_reason carries the cause (denied scope, expired grant, revoked app).

disconnected

Revoked by the user or by you. The stored credential is dropped and calls are refused.

Calling tools

The agent works through Vetta’s connection tools, never the raw credential:

connection_search — discover the tools available on a connected account.
connection_call — invoke a specific tool with arguments.
manage_connections — a meta-tool for listing connected accounts, checking status, and starting a new connection from inside a run.

// what the agent emits, conceptually:
connection_call({
  connection: "conn_8f2c",   // a connected account
  tool: "send_message",
  args: { to: "customer@example.com", subject: "Refund", body: "Done." }
})

Governance

The auth config’s pinned tools are the first governance layer, and they are enforced at the provider: an operation the config was not pinned to is refused before it is dispatched. Above that, which apps an identity may connect and which of the pinned tools are callable is controlled by policy: open, an allowlist, or a blocklist, plus per-connection approval on sensitive actions. Connecting a new app is approval-gated by default. Every call is priced against your budget and drawn from the organization balance.

Pricing

Connection usage is metered per event. These are the rates you are charged:

Meter	Rate
Managed tool call	$0.0003 per `connection_call`
Connected account	$0.10 each (managed account)
Trigger / webhook event	$0.003 per event

A run that discovers and sends one message costs a few managed tool calls — on the order of $0.001 — plus the one-time $0.10 for the connected account. Spend appears as connection line items in the agent’s breakdown and the organization ledger.

Field reference

string

required

The app to connect, by its catalogue id — e.g. zendesk, linear, intercom. Search GET /v1/connections/apps for it; there is no fixed set. The five category words that used to be the only accepted values (email, chat, tracker, crm, docs) still resolve, onto the apps they always meant.

string[]

The operations a connection made from this auth config may call. Omitted, the app’s own featured set is pinned. This is a boundary, not a filter — anything outside it is refused at the provider.

object

Values the app needs before authorization can start — an account subdomain, a region, a workspace. Read them from the app or the auth config (connect_fields); leave them out and the hosted page asks the person instead.

string

default:"managed_oauth"

Auth method on the auth config: managed_oauth (Vetta’s OAuth app), oauth (your own OAuth app credentials), or api_key.

string[]

Scopes requested at authorization. Narrower scopes reduce what a connected account can do.

string

required

The identity a connected account is bound to. One auth config can back many identities.

string

Connected-account state: initiated, active, failed, or disconnected.

string

Present on failed — the cause (denied scope, expired grant, revoked app).

string

The hosted authorization URL the end user opens to authorize. Present while initiated, and it expires — read connect_link_expires_at and mint a new one rather than caching it.

This page is not on a Vetta domain today. The hosted authorization page is served by the connection provider, on the provider’s own host, and it carries the provider’s name in the page title, the heading and a “Secured by” badge. Serving it from connect.vetta.sh is not offered on the current plan; the provider’s own white-labelling covers a logo, an app title and a theme — set in their dashboard, with no API — and removes the badge only when you bring your own OAuth app for that connector. Treat the connect link as a page you hand to an end user, not as part of your product’s surface, until this changes.

Next: the vault

Secrets the agent can use but never see.

Agent

Running an agent

Agent capabilities

Computer

Identity

Team

Two objects

Connecting

The agent can start this itself

Lifecycle

Calling tools

Governance

Pricing

Field reference

Next: the vault

​Two objects

​Connecting

​The agent can start this itself

​Lifecycle

​Calling tools

​Governance

​Pricing

​Field reference

Next: the vault

Two objects

Connecting

The agent can start this itself

Lifecycle

Calling tools

Governance

Pricing

Field reference