> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connections
> Learn how connections work in Langdock, including authentication types, ownership, and sharing options for agents and workflows.
## What Are Connections?
A **connection** is a saved authentication link between Langdock 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.
Each connection belongs to the user who created it. This ensures your credentials remain secure and actions are performed with your access rights.
## Authentication Types
Langdock supports different authentication methods depending on the integration:
| Auth Type | How It Works | Example Integrations |
| ------------------- | ------------------------------------------------------------------- | ------------------------------------------- |
| **OAuth** | You sign in directly with the service and grant Langdock permission | Google Suite, Microsoft 365, Slack, HubSpot |
| **API Key** | You provide an API key from the service | OpenAI, Stripe, custom integrations |
| **Service Account** | An admin sets up a service-level account | Some enterprise tools |
| **None** | No authentication needed | Public APIs |
### 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 Langdock to access specific data
4. **Tokens are stored** securely and refreshed automatically
By default, Langdock'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.
If an OAuth connection expires, is revoked, or is missing a required scope, Langdock asks you to reauthorize it. See [Reauthorize OAuth connections](/en/using-langdock/integrations/connections#reauthorize-oauth-connections) for recovery steps.
OAuth connections always act with your permissions. If you can't access a calendar in Google, the agent using your connection can't access it either.
#### Custom Scopes and Application-Level Permissions
If you set up your own OAuth client, you can request custom scopes beyond Langdock's defaults, including application-level permissions that grant broad access not tied to an individual user. See [Bring Your Own OAuth Client](/en/admin/manage-integrations/bring-your-own-oauth) for setup.
Application-level permissions act independently of any user's access rights and can reach data across your organization. Grant them only when a specific integration requires it.
### Reauthorize OAuth connections
Langdock asks you to reauthorize an OAuth connection when it expires, is revoked, stops working, or is missing a scope an action needs.
In chat, a failed action can show a **Reauthorize** prompt. Click **Reauthorize** to update the connection. For OAuth connections, Langdock starts the regular OAuth flow. After the connection is updated, Langdock 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.
### 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 Langdock
* **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 Langdock 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**. Langdock 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.
A default applies per integration and per user. Each person picks their own default, and a preselected connection on an agent always takes priority.
### 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, Langdock 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.
***
## Sharing Connections via Agents
While connections are personal by default, there's a powerful way to share their capabilities: **attaching connections to agents**.
### 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. This requires the `configurePreselectedConnections` permission.
When using a preselected connection, all users will perform actions using that connection's credentials—regardless of their own accounts.
### 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
**Example:** You create a "Team Calendar Agent" with a preselected connection to a shared team calendar. When any colleague uses this agent, the event is created in the team calendar—but they never see the calendar's credentials.
***
## Sharing Non-OAuth Connections Directly
Connections that use **API Key**, **Service Account**, or **No Authentication** can be shared directly with other users, groups, or your entire workspace.
### Shareable Connection Types
| Auth Type | Directly Shareable? |
| --------------- | :-----------------: |
| OAuth | ❌ No |
| API Key | ✅ Yes |
| Service Account | ✅ Yes |
| None | ✅ Yes |
### 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
If you have an API key connection (or another shareable type), workspace admins and connection owners can share it:
1. Go to **Integrations**
2. Select the integration that has your connection
3. Find your connection in the list and click to manage it
4. Select who to share with:
* **Specific users**: Individual team members
* **Groups**: Entire teams or departments
* **Entire Workspace**: Everyone in the workspace
This is great for shared API keys like translation services, analytics tools, or internal APIs that the whole team should be able to use.
### Who Can Share Connections?
| Role | Can Share |
| ---------------- | ------------------------------------------- |
| Connection owner | ✅ Their own non-OAuth connections |
| Workspace admin | ✅ Any non-OAuth connection in the workspace |
| Regular user | ❌ Only through agents |
***
## Choosing the Right Sharing Method
| Scenario | Recommended Approach |
| -------------------------------------- | -------------------------------------------- |
| Team needs access to your calendar/CRM | Create an agent with pre-configured actions |
| Shared API key for a service | Share the connection directly (if non-OAuth) |
| Personal workflow automation | Use your own connection in your agent |
| Departmental tool access | Share via agent with specific groups |
***
## Summary
| Feature | OAuth | API Key / Service Account |
| ----------------------- | ----- | ------------------------------- |
| User-owned | ✅ | ✅ |
| Direct sharing | ❌ | ✅ (to users, groups, workspace) |
| Share via agent | ✅ | ✅ |
| Automatic token refresh | ✅ | N/A |
| Admin can share | ❌ | ✅ |
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, or is missing a scope. Reauthorize the connection to start the OAuth flow again and restore access. See [Reauthorize OAuth connections](/en/using-langdock/integrations/connections#reauthorize-oauth-connections) for steps.