Connect accounts

Send the user a connect link to connect their own account. They open it, sign in to the app, and Dexby stores the credential for tool calls. Your application does not need to handle that credential.

You need an auth config for each app you offer.

Create a connect linkCopy Anchor Link

import { Dexby } from '@dexby.ai/sdk'

const dexby = new Dexby()

const link = await dexby.createConnectLink({
	userId: 'user_123',
	connectors: ['slack', 'github'],
	redirectUrl: 'https://app.example.com/settings/integrations'
})
if (link.isErr()) throw new Error(link.error.message)

console.log(link.value.url) // send this to the user

curl -X POST "https://api.dexby.ai/v1/connect-links" \
  -H "Authorization: Bearer $DEXBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "user_123", "connectors": ["slack", "github"] }'

A link works once. Anyone holding it can connect an account for the user named by the link until it is used or expires. Send it only to that user.

You can also create a link in the dashboard: Operate → Connections or a user's page under Operate → Users, then Create connect link.

Let the agent askCopy Anchor Link

Inside a session, the model has a dexby_connect_account tool. When a user asks for an app they have not connected, the model can request a connect link. Your application presents that link to the user so they can connect their own account.

Connect an account yourselfCopy Anchor Link

For testing, or when you already hold the credential:

• Dashboard: Build → Auth configs, Connect account on a config, then enter the End user identifier.
• API: POST /v1/connections with the user id and credential fields. See Endpoints.

Several accounts per appCopy Anchor Link

A user can connect more than one account per app, such as work and personal. Calls use the user's default account unless the call or session names another. See Sessions.

Global connectionsCopy Anchor Link

A global connection is an account the project connects once, such as a shared support inbox, that every user of the project can use without connecting anything. It belongs to one project and is visible to every user of that project. Two things keep it contained: a call uses it only where global accounts are allowed, and it runs only the actions an admin allowed it.

Add one in the dashboardCopy Anchor Link

Open Connections and choose Add global account. Pick the auth config it connects through, enter its credential, and you land on its permissions: tick the actions every user may run with it and save. The Global filter on the same page lists every global account; open one to see its GLOBAL badge, its permissions and its activity.

The same flow starts from Build → Auth configs: open a config and choose Connect for everyone under Global connection. The auth configs list shows how many global accounts each config has, and a connector's page in the catalog shows its global accounts on the Connections tab. Only organization owners and admins can add or remove a global account or change its permissions.

With the API, POST /v1/connections with "global": true instead of userId connects one. It starts with no actions allowed until an admin allows some in the dashboard.

Where global accounts are allowedCopy Anchor Link

Global accounts are opt-in. Where nothing opted in, a call behaves as if they did not exist: they are not candidates, not offered as choices, and not suggested to agents.

GET /v1/connections?userId= always lists the user's global accounts, marked "global": true: listing is not using.

Which account a call usesCopy Anchor Link

Where global accounts are allowed, a call chooses by the usual rule over the user's own accounts and the global ones:

1. The account the call or session names, by id, name or label. When a name or label matches both one of the user's accounts and a global account, the call fails with 409 AMBIGUOUS_CONNECTION; name it by id.
2. Otherwise the user's own default.
3. Otherwise the only active account, own or global. A user with no account of their own and one global account uses it.
4. Otherwise 409 AMBIGUOUS_CONNECTION, whose choices mark each global account with "global": true.

PermissionsCopy Anchor Link

Each global account has an explicit allowlist of the actions it may run, chosen by an admin. A new global account allows nothing. An action outside the list is refused with 403 ACTION_DISABLED: '<action>' is not permitted for the shared account '<name>'. Ask an admin to allow it. The account's auth config still applies too: an action the config turned off stays off.

Raw requests through a global account (POST /v1/tools/proxy, a session's dexby_proxy) need the account's Allow proxy (unmodelled endpoints) permission, off by default.

Every permission change is audited as connection.permissions_update, with the actions allowed and revoked and the proxy setting.

Audit and erasureCopy Anchor Link

A global account is never a user's default, and an agent cannot set it as one or disconnect it. Every call through it is still recorded for the user who made it: the audit record's subject is that user, and its detail carries the global account's connectionId and "global": true. Erasing a user never touches global accounts; deleting the auth config removes them.

The hosted Connect page shows an app with a global account as "Available through" your app, so the user knows they need not connect it. They can still add their own.

Apps that need no sign-inCopy Anchor Link

Apps such as Hacker News need no account. Once the project turns one on, every user can run its actions with nothing connected. Sessions report its connection status as not_required, and the Connect page lists it as "No sign-in needed".