Browse documentation

Connect an account

Connect or reconnect a connector in a vault: one-click OAuth, your own OAuth app, an API key or a service account key.

Activating a connector makes its tools available, but a connector that reaches an outside service still needs an account to act as. That connection is what you set up here, and it is stored in a vault rather than on the agent.

How you connect depends on the connector. Each one declares its method, shown as a badge on its Connect dialog and its Set up card: OAuth 2.0, API key or Service account.

Open the Connect dialog

The dialog is titled Connect followed by the connector's name. You reach it:

  • Right after activating the connector, on the Connectors page: activating goes straight on to connecting it. See Connectors (MCP).
  • From the Connectors page later: a connector's ⋯ offers Connect while none of your vaults connects it, and its page has Connect on its Set up card.
  • From a vault: open the vault, click Add credential in its MCP connector keys part and pick a connector. Only active connectors that need a connection are listed.

From the Connectors page, the dialog starts with a Vault picker, your own vault first, so you choose where the connection lives (Agents that use this vault can use Microsoft 365's tools.). From a vault, the connection goes into that vault. Its Instructions fold open on the steps for that connector.

One-click OAuth

The default for an OAuth connector, and the shortest path. Under How do you want to connect?, leave One-click selected (One-click (use the Microsoft 365 app we manage)) and click Connect with the connector. You are sent to the provider, you grant access, and you land back in SPARK with the connection made.

There is nothing to register and no secret to handle. NGT's own registered application asks for the access, and the dialog lists the Requested scopes before you go, so you can see what you are granting. Some providers ask an administrator to approve the application once for the organisation first, as Microsoft 365 does.

Connect Microsoft 365OAuth 2.0Microsoft 365 uses OAuth. You'll be sent to Microsoft 365 to grantaccess. Choose which vault to store it in.InstructionsVaultClaire's vaultAgents that use this vault can use Microsoft 365's tools.How do you want to connect?One-click (use the Microsoft 365 app we manage)Bring your own Microsoft 365 OAuth appRequested scopes: offline_access, User.Read, Files.ReadWrite.All,Sites.Read.All, Mail.ReadWrite, Mail.Send, Calendars.ReadWrite,Chat.ReadWrite, People.ReadConnect with Microsoft 365Skip for now
One-click: NGT's own app asks the provider for access.

Bring your own OAuth app

Choose this when your organisation requires the connection to run through its own registered application, for example so the grant appears under your own tenant's audit trail.

  1. Select Bring your own OAuth app.
  2. Copy the redirect URI shown in the dialog and register it in your provider's OAuth app. The dialog shows the exact URI for that connector, so copy it from there rather than constructing it.
  3. Paste the Client ID and Client Secret from your app.
  4. Click Connect with the connector and grant access at the provider as usual.
Connect Microsoft 365OAuth 2.0Microsoft 365 uses OAuth. You'll be sent to Microsoft 365 to grantaccess. Choose which vault to store it in.InstructionsVaultClaire's vaultAgents that use this vault can use Microsoft 365's tools.How do you want to connect?One-click (use the Microsoft 365 app we manage)Bring your own Microsoft 365 OAuth appClient IDOAuth client ID from your Microsoft 365 appClient SecretOAuth client secretRegister this redirect URI in your Microsoft 365 OAuth app:https://api.nextgatetech.com/mosaic/api/v1/oauth/callback/microsoft-365/Requested scopes: offline_access, User.Read, Files.ReadWrite.All,Sites.Read.All, Mail.ReadWrite, Mail.Send, Calendars.ReadWrite,Chat.ReadWrite, People.ReadConnect with Microsoft 365Skip for now
Bring your own app: register the redirect URI, then paste your app's ID and secret.

Service account

Some connectors authenticate with a key rather than with a person. The Google Cloud connectors work this way: BigQuery, Cloud Storage, Cloud Logging, Cloud Run, Cloud SQL and Firestore.

  1. Create a service account with the access the connector needs, and download its JSON key.
  2. In the Connect dialog, paste the full JSON key into the field (Paste the full service account JSON key).
  3. Click Save.

There is no sign-in round trip, so the connection is live as soon as it saves. The key grants whatever the service account can do, so scope the service account itself rather than relying on SPARK to narrow it.

API key

Paste the key into the field the connector asks for and click Save. Paste only the key itself, with no "Bearer" prefix or line breaks: the dialog refuses a key with spaces or one too short to be whole. Some connectors ask for more than one value, for example a key and an account identifier; the dialog shows a field per value.

GitHub and Linear work this way: a GitHub personal access token, or a Linear personal API key. The connector's page explains where to create each one.

Connect GitHubAPI keyGitHub authenticates with an API key. Paste your key below. Choosewhich vault to store it in.InstructionsVaultClaire's vaultAgents that use this vault can use GitHub's tools.GitHub personal access tokenSaveSkip for now
An API-key connector: choose the vault, paste the key, then Save.

Tokens are refreshed for you

An OAuth connection does not need re-authorising per agent. SPARK holds the connection centrally and hands out a fresh token whenever an agent runs, so one connection works for every agent bound to that vault, and an expired token is renewed without anyone being sent back to the provider.

When a connection expires

Sometimes the provider refuses to renew a connection: consent was revoked, the refresh token expired, or the connection was made with a different OAuth app. SPARK then marks the connection Expired in the vault. Agents keep running with their other connectors, without that connector's tools, and the agent's Vault section shows Missing credentials with the connector's name.

To fix it, open the connector's page under Agent Studio > Connectors and click Reconnect on its Set up card. The Reconnect dialog starts on the vault that holds the connection, and connecting again replaces it. Disconnect, beside it, takes the connection out of a vault.

A connection lives in the vault, not on the agent. Store it in your personal vault when it should act as you alone: it then works only when you ask the agent. Store it in a shared vault when several teammates, agents or workflows should act through the same account. See Vaults.

Where to go next