Connections

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

What Are Connections?

A connection is a saved authentication link between Odeus 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

Odeus 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 Odeus 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 Odeus to access specific data
4. Tokens are stored securely and refreshed automatically

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.

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 Odeus
• 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 Odeus 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.

---

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.