Integrations

Integrations connect Rills to external services. Connect once, then use the integration in any workflow as a trigger or an action.

Available integrations

Rills ships with integrations across five categories: communication tools, project management platforms, CRMs, calendar services, and cloud storage providers.

The integration catalog in your workspace (accessible from the workflow builder) is the authoritative source for available integrations. New integrations are added regularly, so the catalog may include services not listed here.

Each integration has a status: active (available for use), deprecated (still functional but being phased out), or inactive (disabled). The integrations guide covers how to browse the catalog and connect your first integration.

Authentication types

Integrations authenticate using one of four methods:

OAuth 2.0 -- Used by most major services (Google, Slack, Salesforce, etc.). You authorize via the service's login page and grant specific permissions. Rills handles token storage, refresh, and rotation automatically.

API key -- You generate a key in the service's developer settings and paste it into Rills. Common with developer tools, analytics platforms, and services that don't support OAuth.

Basic auth -- Username and password credentials. Used by some legacy APIs and self-hosted services.

None -- No authentication required. For public APIs that don't need credentials.

You can see which auth type an integration uses before connecting it. OAuth integrations handle the most complexity behind the scenes (token expiry, refresh, scope management), while API key and basic auth integrations are simpler to set up.

Credential lifecycle

Each credential in your workspace has one of three statuses:

Active -- Credentials are valid. Workflows can use them without interruption. The lastValidated timestamp shows when Rills last confirmed the credentials work.

Expired -- The access token has expired. For OAuth integrations, Rills attempts automatic token refresh. If refresh succeeds, the credential returns to active. If refresh fails repeatedly, the refreshFailures counter increments and the credential stays expired until you reconnect.

Revoked -- You or the external service revoked access. This happens when you disconnect from the service's side (e.g., removing Rills from Google's "Third-party apps" settings) or when an admin removes the credential in Rills. Revoked credentials cannot be refreshed -- you need to reconnect the integration.

Rills tracks consecutiveFailures per credential and stores the lastError for debugging. If a credential fails repeatedly, any workflow steps depending on it will fail with a descriptive error.

OAuth token refresh

When an OAuth access token expires, Rills attempts an automatic refresh using the stored refresh token. If the refresh succeeds, the credential returns to active and workflows continue without interruption.

If the refresh fails, the refreshFailures counter on the OAuth connection increments. After repeated refresh failures, the credential status moves from active to expired. At that point, the user must re-authorize the integration -- this creates a fresh OAuth connection with new tokens. Re-authorization preserves all existing workflow configurations; only the underlying credential changes.

Credential health monitoring

Each workspace credential tracks health through four fields:

• lastValidatedAt -- Timestamp of the last successful credential validation check
• consecutiveFailures -- Count of sequential failures since the last success (resets to 0 on any success)
• lastError -- The most recent error message from the external service, useful for debugging
• rotatedAt -- When the credential was last rotated (applies to API key credentials)

The system periodically validates credentials. A rising consecutiveFailures count is an early warning sign before a credential fully fails. Monitor this field to catch problems before they break running workflows.

Multiple accounts

You can connect multiple credentials for the same integration -- for example, personal and work Gmail accounts. Each credential is independent: different tokens, different scopes, different health status.

Workflow nodes reference a specific credential, so different workflows (or different steps in the same workflow) can use different accounts for the same service.

Troubleshooting disconnections

Common reasons an integration stops working:

Token expired and refresh failed. OAuth tokens have limited lifetimes. Rills refreshes them automatically, but refresh can fail if the service's refresh token also expired (some services expire refresh tokens after 6 months of inactivity). Fix: reconnect the integration from your workspace settings.

Access revoked from the external service. If you visit Google, Slack, or another service's "Connected apps" page and remove Rills, the credential status moves to revoked. Workflows using that integration will fail until you reconnect. Fix: reconnect in Rills.

Service changed API scopes. Occasionally a service updates their API and requires new permissions. Existing connections with the old scope set will fail for operations that need the new scopes. Fix: reconnect with updated permissions (your workflow configurations are preserved).

Rate limit exceeded. If a workflow sends too many requests in a short window, the service may throttle or reject calls. The workflow step fails with a retryable error. Fix: wait for the rate limit window to reset, or reduce workflow frequency.

Check the credential's lastError field for the specific failure reason. Rills records the most recent error message from the external service, which usually points directly at the problem.

Rate limits

Rate limits vary by integration and plan tier. Each integration enforces its own rate limits based on the external service's constraints. You can view your current rate limit status in the integration settings within your workspace.

When a workflow step hits a rate limit, it fails with a retryable error. If the workflow has a retry policy configured, Rills will automatically retry after a delay. Otherwise, the step fails and you can re-run it manually once the rate limit resets.

Trigger types

Integrations can start workflows through three trigger mechanisms:

Webhook -- The external service sends events to Rills in real-time. This is the fastest option with no delay between the event and your workflow starting. Most major integrations (Slack, GitHub, Stripe) support webhooks. No credit cost for receiving webhooks.

Polling -- Rills checks the external service periodically for new events. There is a small Workflow Credit cost per poll check and a slight delay (seconds to minutes depending on poll interval). Used when the service doesn't support webhooks.

Scheduled -- Rills queries the service on a fixed cron schedule. Similar to polling but runs at predictable times rather than at intervals. Useful for batch operations like "sync all new contacts every morning."

Webhooks are preferred when available: instant, free, and reliable. Polling and scheduled triggers trade some latency and a small credit cost for broader compatibility.

Trigger credit costs

• Webhook: No credit cost for receiving the event. The external service pushes data to Rills.
• Polling: Each poll check costs 0.1 Workflow Credits. A workflow polling every 5 minutes uses approximately 8,640 Workflow Credits per month.
• Scheduled: The schedule check itself has no credit cost. Workflow Credits are consumed by the operations the workflow performs when it runs.

Custom integrations

Available on Business and Enterprise plans. Custom integrations let you connect any service with a REST API. You define:

• Base URL -- The API's root endpoint (e.g., https://api.yourservice.com/v1)
• Authentication -- API key, basic auth, or OAuth configuration
• Operations -- HTTP method, path, parameters, request/response schemas

Custom integrations are workspace-private (visibility: "workspace") -- they're only visible and usable within the workspace that created them.

Custom integrations work exactly like built-in integrations once configured: they appear in the workflow builder, support triggers and actions, and their credentials follow the same lifecycle management.

Setting up a custom integration

1. Define the base URL for the external API (e.g., https://api.yourservice.com/v1)
2. Choose an authentication type: api_key, basic_auth, oauth2, or none
3. Provide auth configuration -- for API key integrations, specify the header name; for OAuth, provide the authorization and token endpoints
4. Define operations with their HTTP method, path, parameter schemas, and required scopes
5. Optionally define a config schema for any integration-level settings users need to provide

Custom integrations use workspace visibility -- they are not shared across workspaces. Only workspace admins can create or modify them.

Custom integrations are available on Business and Enterprise plans.

Scope management

When you connect an OAuth integration, you grant specific scopes (permissions). Each integration operation declares which scopes it requires. For example, a Gmail "send email" operation requires the gmail.send scope, while "read email" requires gmail.readonly.

If you connect with insufficient scopes, operations that need missing scopes will fail with a permissions error. You can reconnect with broader scopes at any time without losing your existing workflow configurations -- Rills updates the credential in place.

Some integrations request all necessary scopes upfront during the initial connection. Others use incremental authorization, where Rills requests additional scopes only when you first use an operation that needs them.

Scope mismatches

Each integration operation declares the scopes it requires via requiredScopes. When you connect an OAuth integration, the scopes you grant are recorded as scopesGranted on the OAuth connection.

If an operation requires a scope you did not grant, that operation fails with a scope error. Other operations that have sufficient scopes continue to work normally.

To fix a scope mismatch: reconnect the integration and grant the additional scopes. Existing workflow configurations are preserved -- only the OAuth connection is updated. You do not lose access to previously granted scopes when reconnecting.

Integration deprecation

Integrations have a status: active, deprecated, or inactive.

A deprecated integration still works, but it may be removed in a future update. If you see a deprecation notice, migrate your workflows to the replacement integration before it becomes inactive.

An inactive integration cannot be used in new workflows. Existing workflows that reference it continue to run, but may fail if the external service is no longer accessible.

For a step-by-step connection walkthrough, see the integrations guide. Integration actions consume Workflow Credits.