Connecting to External Services

Before your workflows can interact with external services like Confluence, Jira, or Monday.com, you need to set up credentials. How this works depends on your deployment type.

Managed Deployments

If you are on the Managed tier (Nemorion-hosted), most popular services are pre-configured. We have already registered the OAuth applications with the major service providers on your behalf. You simply:

1. Click "Connect" next to the service you want to use
2. Log in to the service and approve access
3. Start using it in your workflows

No admin setup is required — we handle the OAuth registration behind the scenes.

Self-Hosted Deployments

If you are running Sovereign on your own infrastructure, you need to register OAuth applications yourself. This is a one-time setup per service.

The Two-Layer Model

Layer 1: Admin registers the OAuth application (once)

An administrator registers the OAuth application details — the client ID and client secret obtained from the external service's developer console. This is done once per service and applies to the entire deployment.

Layer 2: Users authorize their connection (per user)

Individual users click "Connect" and go through the OAuth flow to authorize Sovereign to act on their behalf. They never see or handle client secrets — they just log in to the service and approve access.

This is similar to how you connect apps to your Google account: someone registered the app with Google (Layer 1), and you just click "Allow" when prompted (Layer 2).

API Key Authentication

Some services use API keys instead of OAuth. For these, users provide their API key directly, and it is stored securely alongside OAuth credentials.

Credential Security

All credentials are protected with multiple layers of security:

• Encrypted at rest — credentials and tokens are encrypted using industry-standard encryption before being stored in the database
• Key rotation — encryption keys can be rotated without re-encrypting existing credentials
• Token refresh — OAuth tokens are automatically refreshed when they expire, with distributed locking to prevent race conditions in multi-instance deployments
• Encrypted caching — frequently used tokens are cached in encrypted form to reduce database load while maintaining security

Managing Credentials

Viewing Connections

Users can view their active connections and see which services are connected. Each connection shows the service name, when it was authorized, and its current status (active, expired, or revoked).

Revoking Access

Users can disconnect from a service at any time. This revokes the stored tokens and prevents further API calls to that service on their behalf.

Connection Policies

Administrators can configure policies that control how connections are used:

• Which users or groups can create connections to specific services
• Whether connections can be shared between users
• Audit logging of credential operations

Setting Up a New Service

To connect a new external service to your deployment:

1. Obtain OAuth credentials from the service's developer console. You will need the client ID and client secret. Set the redirect URI to your Auth Service's callback URL.

2. Register the OAuth application in your Sovereign deployment's admin settings, providing the client ID, client secret, and any service-specific configuration.

3. Users connect by clicking the "Connect" button for that service, which launches the OAuth authorization flow in their browser.

For services using API keys, users enter their key directly — no admin registration step is needed.

Next Steps

• Available Connectors — see which services have connectors
• Authentication Setup — configure the authentication layer that manages connections
• Security Overview — learn about the security model for stored credentials