Docs

Connections

A connection is one API token or OAuth grant, sealed to your vault and stored on our servers as ciphertext. This page covers the catalog, what “native” means, how sealing works, custom connections, and connection health.

Catalog vs custom

Most connections come from the built-in catalog: 27 providers, each with a known id, a link to where you generate a key, and instructions for scoping that key correctly. Connect any of them with caddi connect <provider-id>, for example caddi connect vercel.

Anything outside the catalog (an internal API, a niche SaaS) is a custom connection: a slug plus a display name, with no curated tools of its own. Slugs must start with a lowercase letter or digit, contain only lowercase letters, digits, and hyphens, and be at most 64 characters. Catalog provider ids and a couple of reserved words (custom, catalog) can’t be used as a custom slug.

caddi connect custom my-internal-api --name "My internal API"

Native vs secrets-only

Native providers ship curated MCP tools in the gateway: your agent calls something like deploy_project or send_email, and the gateway decrypts your token, calls the provider’s API, and returns the result. The agent never sees the token itself.

Every other catalog provider is secrets-only: there’s no curated tool for it yet, but the connection is still useful. You can pull its value into a project’s .env.local with caddi env pull (allowlisted per project), or expose it to an agent directly through the get_secret tool, which is off by default and has to be explicitly enabled per project.

How sealing works

There’s no OAuth relay for token-based providers: you generate a token on the provider’s own site and paste it in. From the dashboard, that paste is sealed client-side, in your browser, using an X25519 sealed box addressed to your vault’s public key, before anything is sent to our servers. From the CLI, the same sealing happens on your device before the request is made, skipping the browser entirely. Either way, the server only ever receives and stores ciphertext; it never sees the plaintext token, not even for a moment.

A short fingerprint of your vault’s public key is shown on every connect form and by caddi status, so a substituted key is detectable rather than silent. See the security model for the full trust boundary.

The catalog

OAuth-based providers (Gmail, Google Drive, Google Calendar, Canva) are listed for completeness but aren’t connectable yet, marked “coming soon” below.

Provider	Category	Access	Get a key
`airtable` Airtable	Data	secrets only	Create a key: Create a personal access token with the data.records:read and data.records:write scopes for the bases you need.
`anthropic` Anthropic	AI	tools	Create a key: Create an API key scoped to the workspace you want to use.
`canva` Canva	Productivity	coming soon	Connect your Canva account and grant access during the OAuth consent flow.
`cloudflare` Cloudflare	Infra	tools	Create a key: Create a custom API token with the minimum permissions for the zones or account resources you need.
`elevenlabs` ElevenLabs	AI	secrets only	Create a key: Create an API key with access limited to the products you plan to use.
`figma` Figma	Productivity	secrets only	Create a key: Create a personal access token with access limited to the files you need to read.
`fly` Fly.io	Infra	secrets only	Create a key: Create a personal access token scoped to your account for deploying and managing apps.
`github` GitHub	Infra	tools	Create a key: Create a fine-grained personal access token, or a classic token with repo scope only.
`gmail` Gmail	Productivity	coming soon	Connect your Google account and grant Gmail access during the OAuth consent flow.
`google-ai` Google AI	AI	secrets only	Create a key: Create an API key for the Gemini API in the project you want billed.
`google-calendar` Google Calendar	Productivity	coming soon	Connect your Google account and grant Calendar access during the OAuth consent flow.
`google-drive` Google Drive	Productivity	coming soon	Connect your Google account and grant Drive access during the OAuth consent flow.
`groq` Groq	AI	secrets only	Create a key: Create an API key with default access for the project you are using.
`linear` Linear	Productivity	tools	Create a key: Create a personal API key with access to the workspace you want to automate.
`neon` Neon	Data	tools	Create a key: Create an API key scoped to your account for managing projects and branches.
`netlify` Netlify	Infra	tools	Create a key: Create a new personal access token under OAuth applications for managing your sites.
`notion` Notion	Productivity	tools	Create a key: Create an internal integration and copy its secret, then share only the specific pages or databases it needs.
`openai` OpenAI	AI	tools	Create a key: Create a secret API key scoped to the project you want to use.
`posthog` PostHog	Monitoring	tools	Create a key: Create a personal API key scoped to the project you want to query.
`railway` Railway	Infra	secrets only	Create a key: Create an account or project token with access limited to the project you want to deploy from.
`replicate` Replicate	AI	secrets only	Create a key: Create an API token with default scope for your account.
`resend` Resend	Email	tools	Create a key: Create an API key with sending access limited to the domain you plan to use.
`sentry` Sentry	Monitoring	tools	Create a key: Create an auth token with project:read scope for the projects you monitor.
`slack` Slack	Productivity	secrets only	Create a key: Create an app, install it to your workspace, and use the bot token with only the scopes your integration needs.
`stripe` Stripe	Payments	tools	Create a key: Create a restricted API key with only the permissions your integration needs, and prefer a test mode key until you are ready for live traffic.
`supabase` Supabase	Data	tools	Create a key: Create a personal access token for managing projects through the Supabase Management API.
`vercel` Vercel	Infra	tools	Create a key: Create an access token scoped to the team or project you want to manage.

Reconnect, disconnect, and health

A connection shows one of three health states in the dashboard and caddi status: verified, once we’ve confirmed the token works against the provider’s own API; not yet verified, for providers we don’t probe or before that check has run; and needs reauth, when the provider has rejected the token. Reconnecting replaces the sealed ciphertext with a freshly pasted token, using the same flow as the initial connect. Disconnecting removes the connection entirely; any project scoping that referenced it stops resolving.