Concepts

Integrations

An integration is a project-scoped connection to an external service. It stores the credentials, OAuth tokens, install IDs, and config that provider-backed actions, event triggers, and reference pickers need.

Automations reference provider capabilities by action or event name. Raw credentials never appear in an automation spec.

Integrations or secrets?

Both hold sensitive values:

Use an integration when Mobius knows about the provider. The connect flow performs OAuth or collects the right credential shape, and server actions such as slack.message.post or github.issue.add_labels pick the credentials up automatically.
Use a secret when the credential belongs to your own worker code or to a provider Mobius does not model yet.

If a provider appears on the Integrations page, use the integration. Otherwise use a secret and a worker action.

Provider catalog

The app reads the provider catalog for the project:

GET /v1/projects/{project}/integrations/providers

That catalog is the source of truth for:

Field	Why it matters
Provider ID and display metadata	What appears in the Integrations page.
Connection state	Whether the provider is connected, built in, unavailable, or needs setup.
Connect mode	OAuth redirect, inline API key, webhook setup, service credential, or a built-in provider that needs no customer credential.
Auth kind	Which credential shape Mobius stores for the provider.
Events	Triggerable provider events such as `github.pull_request.opened` or `slack.event`.
Actions	Automation-callable actions backed by that provider.
Reference types	Pickers for values such as Slack channels, Linear issues, GitHub repos, or table names.

The event catalog and action catalog are also available directly:

mobius catalog list-events
mobius catalog list-actions
mobius catalog get-action github.issue.add_labels

Built in vs. connected

Provider readiness is not all-or-nothing:

Built-in providers are ready without a customer credential. They still appear in catalogs so actions and events can be discovered.
Connected providers store customer-owned OAuth grants, API keys, app installations, webhook setup, or service credentials.
Catalog-only providers may appear with planned actions or events that are documented but not currently runtime-backed for the project.
Unavailable providers may be disabled by environment, billing, or missing platform configuration.

Use the catalog readiness field rather than assuming that a provider logo means every action and event is callable right now.

Events and recent activity

Connected integrations emit canonical provider events into Mobius. Those events are persisted, then converted into public source events that triggers and wait_for_event steps can match.

Recent integration events are available through the app and the API:

GET /v1/projects/{project}/integrations/events
GET /v1/projects/{project}/integrations/events/{event_id}

Use these when a trigger did not fire and you need to know whether Mobius received the provider event, whether it became a source event, and whether downstream processing succeeded.

Reference pickers

Many provider actions take stable external references: a Slack channel, a Linear team, a GitHub repository, a Jira project, a table, or a Google Sheet. Reference picker metadata tells the app how to search and resolve those values without putting provider-specific lookup code in the automation editor.

When a picker is available, prefer it over hand-typed IDs. It avoids stale names, missing permissions, and malformed inputs.

Rotation

Rotate credentials from the provider's integration detail page. The automation spec keeps pointing at the same provider actions and events; Mobius swaps the stored credential behind the scenes.

What not to do

Do not put plaintext keys in inputs or step with blocks. Those land in run history, event logs, and audit records. Use an integration for known providers and a secret for everything else.

Actions call provider-backed server actions.
Triggers receive provider source events such as github.issues.opened, slack.event, and linear.issue.created.
Source events explains provider event envelopes.
Secrets are the other place sensitive values live.