Connecting a Provider
Connecting a third-party service to Otesse is a guided process that takes you from the integration catalog through authentication to a verified, healthy connection. This page walks through every step, including what happens behind the scenes at each stage.
Prerequisites
Before connecting an integration, ensure:
- You are logged in with an active session
- You have the
settings.editpermission for your organization - The provider you want to connect is active in the catalog
- Any required dependencies are already connected (some providers depend on others)
If you have settings.view permission, you can browse the catalog but cannot initiate connections.
Step-by-Step Connection Flow
Step 1: Browse the Catalog
Navigate to Settings > Integrations > All Integrations. You will see provider cards organized by category. Each card shows:
- Provider name and logo
- Brief description
- Category badge
- Connection status (Connect button or "Connected" indicator)
Use the search bar to find a specific provider, or filter by category using the sidebar.
Step 2: Click "Connect"
Click the "Connect" button on the provider card. If the provider has unsatisfied dependencies (e.g., requires Stripe to be connected first), a modal will appear explaining the dependency and linking to the required provider.
Step 3: Authenticate
The authentication method depends on the provider:
For API Key providers (most common in Otesse):
A modal form appears with fields derived from the provider's credential requirements:
| Field | Description |
|---|---|
| API Key | The primary API key from the provider's dashboard |
| API Secret | Additional secret (if the provider requires it) |
| Account ID | Account identifier (if the provider requires it) |
Enter your credentials and click "Connect." The system encrypts your credentials using AES-256-GCM before storing them — plaintext credentials are never saved to the database and never logged.
For OAuth providers:
The system redirects your browser to the provider's authorization page. After you grant access, you are redirected back to Otesse with an authorization code that is exchanged for encrypted access tokens.
Step 4: Verify Connection
After credentials are stored, the system runs a health check:
- Decrypts your stored credentials
- Makes a lightweight API call to the provider (e.g., fetching account info)
- Measures response time
- Records the health check result
The modal shows a progress indicator: "Verifying connection..." This typically takes 2-10 seconds.
Step 5: Connection Confirmed
On success:
- The modal shows a green checkmark: "[Provider] connected successfully"
- A toast notification confirms the connection
- The provider card in the catalog updates to show "Connected" with a green status dot
- The Connected Apps tab immediately shows the new connection
Handling Failures
If the health check fails, the modal stays open with an error message:
| Failure Type | Message | Action |
|---|---|---|
| Invalid API key | "The API key you entered is invalid. Please check your credentials." | Re-enter credentials |
| Provider unreachable | "Could not reach [Provider]. The service may be temporarily unavailable." | Try again later |
| Rate limited | "Connection test was rate limited. Please wait a moment." | Wait and retry |
| OAuth denied | "Connection was cancelled. You denied access." | Re-initiate from catalog |
Failed connections do not leave orphaned data — credentials are cleaned up and the instance status is set to "error," allowing you to retry.
What Gets Created
When you successfully connect a provider, the system creates:
| Record | Purpose |
|---|---|
| IntegrationInstance | Your organization's activation of this provider (if it does not already exist) |
| IntegrationConnection | Your personal authenticated link to the instance |
| IntegrationCredential(s) | Your encrypted API key, access token, and/or refresh token |
| IntegrationHealth | Initial health check record with response time and status |
| IntegrationAuditLog | Audit entry recording who connected, when, and how |
After Connecting
Once connected, the provider appears in your Connected Apps tab. Depending on the provider, you may need to:
- Configure resources — Add sender emails (Postmark), phone numbers (Quo), or webhook endpoints (Stripe)
- Set up sync jobs — Configure data synchronization if the provider supports it
- Configure webhooks — Set up inbound webhook endpoints to receive events from the provider
These post-connection steps are covered in their respective documentation sections.
Currently Connected Providers
Otesse ships with seven providers pre-configured and ready to connect:
| Provider | Category | Auth Type | Resources |
|---|---|---|---|
| Postmark | Communication | API Key | Sender emails (add/edit/delete, set default) |
| Stripe | Payment | API Key | Webhook endpoints, connection status |
| Mapbox | Mapping | API Key | Active/inactive toggle |
| Google Maps | Mapping | API Key | Active/inactive toggle |
| Geoapify | Mapping | API Key | Active/inactive toggle |
| Anthropic | AI | API Key | Model selection, usage monitoring |
| Quo (OpenPhone) | Communication | API Key | Phone numbers (add/edit/delete, set default) |
All seven providers authenticate via API key stored in environment variables — no OAuth flow is required.
On this page