Connections

Learn how connections work in ajan, including authentication types, ownership, and sharing options for agents and workflows.

What Are Connections?

A connection is a saved authentication link between ajan and an external tool. When you connect your Google Calendar, HubSpot, or any other integration, you're creating a connection that stores the credentials needed to interact with that service.

Authentication Types

ajan supports different authentication methods depending on the integration:

OAuth Authentication

Most popular integrations use OAuth, the industry-standard protocol for secure authorization. When you connect via OAuth:

1. You're redirected to the service's login page (e.g., Google, Microsoft)
2. You sign in with your own account
3. You grant permissions for ajan to access specific data
4. Tokens are stored securely and refreshed automatically

By default, ajan's OAuth client requests delegated permissions. These act on behalf of the signed-in user, so every connection uses that user's own access rights.

Your workspace admin can configure custom OAuth clients for the entire workspace or specific groups. When you create a connection, a matching group client takes priority over the workspace client. Your connection stays linked to the client selected during setup, even if your group membership changes later.

If no active client matches your account, or if two active group clients match your memberships, ajan cannot create the connection. Contact your workspace admin to update the client or group assignments.

If an OAuth connection expires, is revoked, or is missing a required scope, ajan asks you to reauthorize it. See Reauthorize OAuth connections for recovery steps.

Custom Scopes and Application-Level Permissions

If you set up your own OAuth client, you can request custom scopes beyond ajan's defaults, including application-level permissions that grant broad access not tied to an individual user. See Bring Your Own OAuth Client for setup.

Reauthorize OAuth connections

ajan asks you to reauthorize an OAuth connection when it expires, is revoked, stops working, is missing a scope an action needs, or its custom OAuth client was removed by a workspace admin.

In chat, a failed action can show a Reauthorize prompt. Click Reauthorize to update the connection. For OAuth connections, ajan starts the regular OAuth flow. After the connection is updated, ajan can retry eligible failed requests automatically.

To reauthorize an OAuth connection manually:

1. Go to Integrations.
2. Open the integration whose connection needs attention.
3. Open the connection's actions menu and select Reauthorize.
4. Sign in with the account that should own the connection and approve the requested scopes.

Active workflows that use an invalid connection also appear on Monitor under Workflows to reconnect, before a later run fails. Click Review on the row. If you own the connection, click Reconnect in the dialog.

API Key & Service Account Authentication

These authentication types require you to manually provide credentials:

• API Key: Copy an API key from the service's settings and paste it into ajan
• Service Account: Provide service account credentials (often a JSON file or key pair)

These are typically used for services that don't support OAuth or for admin-level integrations that need broader access.

---

Connection Ownership

By default, connections are user-based and not shareable. This means:

• You can only see and use connections you created
• Actions performed use your access rights and permissions
• Your credentials are never exposed to other users
• Other users cannot directly use your OAuth connections

This design ensures security and compliance—your authorization remains yours.

Why User-Based?

When you authorize ajan to access your Google Calendar, you're granting permission for actions to be performed as you. Sharing that connection with others would mean they could act on your behalf, which violates the trust relationship established during OAuth consent.

---

Setting a default connection

If you have more than one connection to the same integration (for example, a personal Google account and a work Google account), you can mark one as your default. ajan then uses your default connection automatically whenever an agent or workflow needs that integration and no specific connection has been preselected.

When to use a default connection

• You maintain multiple connections to the same service and want one to be used by default.
• You share workflows or agents with teammates and want them to fall back to your default connection when no preselected one is configured.
• You want to avoid being prompted to pick a connection every time an action runs.

How to set a default connection

1. Go to Integrations and open the integration you want to configure.
2. Find the connection you want to use by default under Your connections or Shared connections.
3. Open the connection's actions menu and select Set as default.

The connection is marked with a Default label. To change your default, set another connection as default; to clear it, open the actions menu again and select Remove default.

How defaults are applied

When an action runs, ajan chooses a connection in this order:

1. The preselected connection configured on the agent or action, if any.
2. Your default connection for that integration, if you have set one.
3. A prompt asking you to pick a connection from those available to you.

A workspace API key does not use a person's default connection. Share the connection with that key, or preselect it on the agent.

---

Using shared connections in agent actions

Connections stay personal by default. To let other people run an integration action with a selected connection, attach the connection to that action in an agent.

Configure the preselected connection in the agent editor, not from the integration page. Other people do not get direct access to the connection. They can only use it when they run that action through the shared agent.

How to configure a preselected connection for an agent action

1. Navigate to Agents in the sidebar and open or create an agent.
2. In Actions, click Add action and select the integration action.
3. Select No, all users should use the same, preselected connection.
4. Choose the connection and click Add action.
5. Publish the agent and share it with the people who should run the action.

People who use the agent can run that action with the preselected connection without seeing its credentials.

How It Works

When you add an action to an agent, you choose how authentication works:

1. "Their own credentials" (default) — Each user who uses the agent authenticates with their own account. They'll be prompted to connect if they haven't already.
2. "Preselected connection" (advanced) — You select a specific connection that all users will use. To preselect an OAuth connection, you need the Share OAuth connections permission.

Use Cases

Default mode (their own credentials):

• Each team member connects their own Google Calendar
• Actions appear in their own calendars
• No credential sharing needed

Preselected connection mode:

• A shared team calendar that everyone posts to
• A central CRM account for all sales reps
• A company Slack bot account

---

Sharing Non-OAuth Connections Directly

Connections that use API Key, Service Account, or No Authentication can be shared directly with other users, groups, workspace API keys, or your entire workspace.

MCP connections that use Authorization: Basic (base64-encoded) count as API Key connections.

Shareable Connection Types

Why OAuth Can't Be Shared Directly

OAuth tokens represent a specific user's authorization and consent. Sharing them would:

• Violate the user's agreement with the service provider
• Create security risks if tokens are leaked
• Make it impossible to track who performed which action

How to Share Non-OAuth Connections

Workspace admins can share API Key connections and other directly shareable connection types from the integration page:

1. Go to Integrations
2. Select the integration that has your connection
3. Open the connection's actions menu and select Share connection
4. Select who to share with:
   • Specific users: Individual team members
   • Groups: Entire teams or departments
   • Workspace API keys: Keys owned by service accounts
   • Entire Workspace: Everyone in the workspace

Search workspace API keys by name. Only active, unexpired keys in your workspace appear. Existing grants show the key name. Active keys show the Workspace API key label, while expired, revoked, and unknown keys show their status. You can remove them from the same sharing dialog.

If you call an agent with a workspace API key, share the connection with that key or preselect it on the agent. The key does not use the creator's personal connections.

Who Can Share Connections?

---

Choosing the Right Sharing Method

---

Summary

Understanding how connections work helps you build secure, collaborative workflows. Use agent-based sharing for OAuth connections, and direct sharing for API keys and service accounts when appropriate.

FAQ

A connection is tied to the user or workspace setup that created it, depending on the integration and sharing configuration. If an agent, chat, or workflow cannot use a connected tool, first check whether the required connection is available to that context and whether the right user has granted access.

Connections must be available wherever the integration is used. A connection that works in one chat or for one user may not automatically be available to another user, agent, or workflow. Check the integration's sharing settings, the connected account, and whether the action is enabled for the target agent or workflow.

An integration asks you to reconnect when its OAuth connection has expired, was revoked, stopped working, is missing a scope, or used a custom OAuth client that a workspace admin removed. Reauthorize from chat, Integrations, or Monitor under Workflows to reconnect. See Reauthorize OAuth connections for steps.