Skip to content
Documentation
On this page

Connect an account

Save a credential once as an account, from the dashboard, the app you are configuring, or an agent, then link it to any app that needs that provider.

An account is one saved set of credentials for one provider. You connect it once. Every app that needs that provider can use it, and none of them holds a second copy.

There are two kinds of credential, and the provider decides which it accepts:

  • Secrets: fields you paste, such as an API token, or an email and a key.
  • OAuth: browser sign-in or a client ID and secret for machine-to-machine access. Executor stores and renews the resulting tokens.

From the hosted dashboard

Choose Connect new account at the end of a provider’s list on the app’s Accounts tab, then choose Connect to start browser sign-in. If the provider needs credentials, enter them in the same dialog. The connection dialog contains the sign-in methods supported by the provider.

The dialog uses the provider fields already loaded with the app. Opening it does not create a connection or fetch the fields again. A connection is created when you submit; retries in that dialog reuse the same request.

OAuth setup is checked in the background and reused across forms. If Executor can use a saved client or register one automatically, the dialog can connect without asking for client details. If your own client is required, its fields appear immediately. A failed check offers Retry without guessing which setup to show. Client IDs and secrets stay on the server during these checks.

The provider’s code declares the grant, endpoints, scopes, and authentication method. Open Advanced below Connect to review Required permissions. The dialog asks only for a client ID and, when required, a client secret. For browser sign-in, copy the fixed redirect URL into the OAuth app’s settings. Machine-to-machine connections complete in the dialog and need no browser redirect.

If saved OAuth client details are wrong, open Advanced below the Connect button, choose Change next to OAuth client, and enter the replacement. Executor saves manual client details only after a successful sign-in. A failed replacement keeps the previous client and account. If browser sign-in rejects the client, Update client details opens the form again.

You name an account after it connects. Executor names each new account Default, then Default 2, and so on when that name is already in use for the provider. Once the account is saved, or browser sign-in returns, a Name this account dialog offers to rename it to something such as “Work” or “Personal.” Closing it keeps the default. Reconnecting keeps the existing name. You can also rename an account later from its detail page.

Completing a connection saves the account and links it to this app. There is no separate step. Browser sign-in returns to the app’s Accounts tab; cancelling or failing sign-in offers a direct way back to the app.

The Accounts tab lists the accounts you linked to the app under each provider. Link an account adds another saved account you can use, and Unlink removes one from the app. Connect new account at the end of the list adds an account and links it. Each change is saved immediately. Members who can view an app but not use it cannot change its links.

Unlinking keeps the saved account available to other apps. When no app uses it any more, Executor offers to delete it. The global Accounts page lists saved accounts and the apps that use them.

Locally, every saved account for a provider the app requires is linked to it. There is nothing to link or unlink.

You can link several accounts for one requirement. For a single-account requirement, each call then chooses one; see “Choosing an account per call” below.

From an agent

An agent can start the same flow. It must never ask you for a secret in chat, and must never read a token out of your files. It asks Executor for a connection link and gives you the link; you finish in your browser.

return await tools.executor.accounts.connect({
  path: { organization: "<organization-id>", app: "<app-id>" },
  body: { requirement: "vercel" },
});
return await tools.executor.accountConnect.issue({
  body: { owner: "alice", target: { app: "<app-id>", requirement: "vercel" } },
});

Locally, supply either target, to connect an account for an app requirement, or provider, to save an account without linking it to any app. Not both.

Check whether you finished:

const connection = await tools.executor.accounts.connection({
  path: { organization: "<organization-id>", connection: "<connection-id>" },
});
return connection.state;
const connection = await tools.executor.accountConnections.get({
  path: { connection: "<connection-id>" },
});
return connection.state;

Completed means the account is saved. If the request named an app, the account is also linked to it, in the same transaction. If the app’s requirement changed while the request was open, the request fails with AccountConnectionTargetChanged rather than saving the account.

A pending request expires after thirty minutes. Issue a new one if it does.

On hosted, an agent links an existing account with appAccounts.link({ path: { organization, app, account } }) and removes it with appAccounts.unlink. The account’s provider must be one the app requires.

Choosing an account per call

A requirement with one linked account uses it. With several linked to a single-account requirement, each call names one in the reserved $accounts input, keyed by requirement:

return await tools.vercel.projects.list({ $accounts: { vercel: "<account-id>" } });

Without a choice the call fails with AccountChoiceRequired, listing the linked accounts’ labels and IDs. Executor never picks one. A .many() requirement uses the chosen accounts, or every linked account when the call names none.

Changing and removing an account

You can rename an account, replace its credentials, and remove it. Replacing credentials keeps the same account, so every app linked to it keeps working.

Removing an account removes its links. An app left with no linked account for a requirement exposes no tools until you link or connect another. Executor does not substitute a different account.

Was this page helpful?