19 · Connect · Integrations

Where outside tools become part of the work.

19 / 19

An integration is a connected identity plus the tools it unlocks — Gmail to read a thread, HubSpot to update a deal, Meta Ads to raise a spend cap. Everything filed from an integration carries its pin; anywhere that pin appears, you can trace it back to the account that sourced it.

19.1Catalog

One grid. Flat gaps. Connected rises.

Tiles sit on a hairline grid — no card shadows, no rounded corners, just the signal rail on the left edge of connected ones. Logo, name, short description, slug chrome. The green signal is the whole "you're linked in" story.

Connected

Gmail

Read threads, draft replies, watch labels. Sends on your behalf with your permission.

gmail
Connected

HubSpot

Deals, contacts, notes. Two-way sync for pipeline changes and ownership.

hubspot
Connected

Meta Ads

Campaigns, spend caps, creative. Surfaces in inbox when a cap is hit.

meta-ads
Connect

Slack

Channel summaries, DM triage, scheduled nudges.

slack
Connect

Notion

Read pages and databases. Turn a page into a figment, or a database into a board.

notion
Connect

Stripe

Customers, subscriptions, invoices. Read-only unless you grant write scopes.

stripe

Rail vs. badge. Both ride connected tiles and they're not saying the same thing. The 2px rail is for the eye scanning the grid — the connected subset lights up at a glance, no reading. The badge names the state once you're focused on a tile. Disconnected tiles drop the rail and repurpose the badge as the action prompt (Connect).

Filter chips — All, Connected — pin to the left of search. Provider-type filter (Composio, direct, custom) hides behind the dropdown. Pagination loads more in the same grid; no second page.

19.2Identity

An integration is the provider. An identity is the account.

One Gmail integration, many Gmail identities — "Work Gmail", "Ops inbox", "Founder@". Identities carry their own name, description, status, and the label the provider hands back (usually the email). Everywhere an item mentions Gmail, it's actually mentioning a specific identity.

Gmail 2 connected accounts
  • Work Gmail sam@ascending.ai
    synced 4m ago
  • Ops inbox ops@ascending.ai Token expired — re-auth to resume.
    2d ago

Display rules. External label wins when it's present (it's what the provider authoritatively calls this account). Fall back to the user's chosen name. Never show both at equal weight — one leads, one follows.

19.3Auth

One button and a name.

Most connections are a click: pick a name, sign in, done. Custom OAuth apps, scope granularity, and alternate schemes stay out of the way until asked for. Both states stacked below — the default shape above, the power expansion underneath. Field vocabulary matches §13 Forms.

Default · first-time state
HubSpot Deals, contacts, notes. Two-way sync for pipeline changes.

Requests read on deals, contacts, and notes by default. Need finer control or your own OAuth app? Those live in power mode.

You'll be redirected to sign in with HubSpot.
Power mode · disclosed on request
HubSpot Deals, contacts, notes. Two-way sync for pipeline changes.
Scheme
Identity
App credentials
Before you connect HubSpot workspaces on SSO need an admin to approve Figments before teammates can sign in. If the redirect lands on a permissions page, ask your admin to allow the app.
Scopes Choose which permissions this connection should request.
You'll be redirected to sign in with HubSpot.
19.4Toolboxes

Bundles of tools an agent can hold.

A toolbox is a named set of integrated identities an agent is allowed to use. Boards override at the board level. Platform capabilities (search, memory, timers) are always in hand — a toolbox only adds to that base.

Sales ops 4 tools
  • MGmail · Work Gmail
  • HHubSpot · Work HubSpot
  • #Slack · #sales-floor
  • Calendar · Sam
Growth 3 tools
  • Meta Ads · Spring launch
  • GGoogle Ads · Primary
  • AAnalytics · ascending.ai
Finance Empty

Add Stripe, Ramp, or QuickBooks when you're ready to let agents touch money-flavoured things.

19.5Provenance

A pin follows every integration-sourced thing.

Anything sourced from an integration — an inbox item, a chat quote, an item-view peek — carries a pin back to its origin.

integ-<slug>
Click → jumps to the identity behind the pin. Hover → reveals the account label.
Inbox item
integ-gmail Reply to Sarah @ Acme? 42m · Work Gmail
Chat quote
integ-hubspot
Deal Acme — Q2 Renewal moved from Negotiation to Closed Won.
via Work HubSpot · 12m
Item-view peek
Spring Launch · ad set 03
Spent today
$5,000 / $5,000
Cost per lead
$18 (target $22)
Source
integ-meta
Board binding
Board · Q3 Launch
MGmail · Work Meta · Spring AAnalytics
Overrides workspace toolbox for this board.
19.6Lifecycle

Five states, one dot, a quiet recovery path.

Status lives on the identity, not the integration. A Gmail with two accounts can have one healthy and one expired — the integration itself is neither.

Connected authorized, syncing, ready for tools
Pending waiting on the provider's OAuth callback
Expired token lapsed — gentle nudge, one-click reconnect
Failed provider rejected the last call; show the reason
Disconnected user removed the link; keep the slot, drop the keys
Empty · no integrations yet

Nothing connected yet

Connect a tool to give your agents something to do. Start with Gmail or HubSpot.

Loading · catalog
Disconnect · confirm in place
Work Gmail sam@ascending.ai 3 agents will lose access: Sales ops, Growth, Inbound triage. Keys are cleared; history stays.
Failure whisper · first callback
Ops HubSpot ops@ascending.ai Upstream said: insufficient scope: crm.objects.deals.write. Re-auth to add it.
Re-auth failed · escalated
Ops HubSpot ops@ascending.ai Second attempt blocked: workspace admin revoked the OAuth app. Ask your admin to re-approve, or drop this slot for now.
19.0Principles

Rules the catalog lives by.

A
The identity is the unit, not the integration.

A provider can host many accounts. Status, names, scopes, and pins all live on the identity. Integrations are the catalogue entry.

B
Provenance never gets lost.

Every surface that shows integration data carries a pin back to the identity. No item ever becomes "just data" — you can always trace it.

C
Quick connect first. Power mode hidden.

A first-timer sees one button and a name field. Custom OAuth apps, granular scopes, and connection fields disclose only when asked for.

D
Scopes are visible before the redirect.

The user should never click "Connect" and then discover what they just handed over. Chips are in hand, checkable, obvious.

E
Failure is legible and actionable.

The provider's reason, in one sentence. A single button to fix it. Never "An error occurred" without telling which scope or token failed.

F
Disconnect is reversible; destroy is rare.

Disconnect empties the keys but keeps the identity — name, history, bindings intact. Reconnect from the same row restores the link in one click. Removing the slot entirely is a separate, explicit step with its own confirmation. Both happen in place, no modal jump.