Connected accounts

When an agent connects a third-party account (see Connecting an account), it can read that account’s credentials through the agent API to make calls on the user’s behalf. This is what an integration’s tools use under the hood; you can use the same methods when building your own.

All examples use the @alfe.ai/agent-api-client. Every method resolves against the accounts in the agent’s own scope — an agent can only read credentials for accounts it has access to.

Multiple accounts per provider

A single agent can connect more than one account for the same provider — two GitHub logins, several Xero organizations, multiple Google accounts. The get<Provider>Accounts() methods return every connected account for that provider, each with a stable identifier you use to pick one:

const { accounts } = await client.getGithubAccounts();
// GET /agent/connect/github/accounts

for (const a of accounts) {
  console.log(a.login, a.accessToken); // pick the account by its `login`
}

{
  "data": {
    "accounts": [
      {
        "connectionId": "con_…",
        "accountIdentifier": "octocat",
        "login": "octocat",
        "displayName": "The Octocat",
        "accessToken": "gho_…",
        "scopes": "repo,read:org",
        "connectedAt": "2026-06-01T00:00:00.000Z"
      }
    ]
  }
}

The stable per-account selector differs by provider — for GitHub it’s login, for Xero and Salesforce it’s the organization id, for Notion the workspace id, for Google and Microsoft the account email. When you build a tool that touches an account, require that selector as an argument so an account is always chosen deliberately.

Available account methods

Provider	Accounts (multi)	Refresh (per account)
GitHub	`getGithubAccounts()`	— (tokens don’t expire)
Google	`getGoogleCredentials()` (returns `accounts`)	—
Xero	`getXeroAccounts()`	`refreshXeroAccountToken(orgId)`
Notion	`getNotionAccounts()`	—
Atlassian	`getAtlassianAccounts()`	`refreshAtlassianAccountToken(email)`
MYOB	`getMYOBAccounts()`	`refreshMYOBToken()`
Salesforce	`getSalesforceAccounts()`	`refreshSalesforceAccountToken(orgId)`
Microsoft 365	`getMicrosoftAccounts()`	`refreshMicrosoftAccountToken(id)`

Each get…Accounts() method returns the fields that provider’s API needs — for example Xero and Salesforce include an instanceUrl / accessTokenExpiresAt, Atlassian includes the list of accessible sites (availableSites), and Google includes the OAuth client id and secret.

Refreshing an expiring token

Providers whose access tokens expire expose a per-account refresh method. Target the specific account by its stable identifier — tokens aren’t interchangeable across accounts:

const { accessToken, accessTokenExpiresAt } =
  await client.refreshXeroAccountToken("<xero-org-id>");
// POST /agent/connect/xero/accounts/{orgId}/refresh

GitHub tokens don’t expire, so there is no GitHub refresh method — if a token is revoked, re-run the connect flow.

Fetching one connection by id

If you already know a connection’s stable connectionId (for example from listIntegrations() or a get…Accounts() result), you can fetch just that connection’s credentials:

const creds = await client.getConnectionCredentials("con_…");
// GET /agent/connect/connections/{connectionId}/credentials

The endpoint enforces that the connection is in the calling agent’s scope, so a connection the agent can’t see comes back as forbidden.

Handle these carefully

The values returned here are live access tokens and, for some providers, OAuth client secrets. Use them to make the API call you need and don’t persist or log them — request them again when you need them next. See Connecting an account for how accounts are authorized in the first place.