OAuth 2.1 Flow
How Ferrule authorizes access to third-party services on behalf of your organization.
OAuth 2.1 Flow
When you connect an integration in Ferrule, you go through an OAuth 2.1 authorization flow. This is the industry-standard way to grant Ferrule permission to act on your organization's behalf without sharing your passwords.
Step-by-step authorization
-
Initiate — In the Ferrule dashboard, click Connect next to an integration. Ferrule redirects your browser to the integration's login page.
-
Authorize — You log in to the third-party service (e.g., Clio, Slack, Asana) and grant the requested permissions. You are granting access to Ferrule's registered OAuth application, not to arbitrary third parties.
-
Callback — The integration redirects back to Ferrule with a short-lived authorization code.
-
Token exchange — Ferrule's server exchanges that code for an access token and a refresh token. This exchange happens server-to-server; your browser never sees the tokens.
-
Encrypted storage — Both tokens are encrypted with AES-256-GCM and stored in Ferrule's database. Only your organization's server can decrypt them.
-
Ready — Ferrule is now authorized. Your AI assistant can call tools for this integration immediately.
Token lifecycle
| Token | Purpose | Lifetime |
|---|---|---|
| Access token | Authorizes API calls to the integration | Minutes to hours (varies by provider) |
| Refresh token | Obtains a new access token when the old one expires | Long-lived; may be single-use or reusable |
Ferrule automatically refreshes the access token before each gateway call when it is within 5 minutes of expiry. You do not need to re-connect integrations manually unless you revoke authorization from the third-party service's settings.
PKCE
For integrations that support it, Ferrule uses PKCE (Proof Key for Code Exchange). PKCE is a security extension that prevents a malicious actor who intercepts the authorization code from being able to exchange it for tokens — because they do not possess the corresponding cryptographic proof that Ferrule generated at the start of the flow.
In practice, PKCE is transparent to you. Ferrule handles it automatically.
Revoking access
To disconnect an integration:
- Open Dashboard → Integrations.
- Click Disconnect next to the integration.
Ferrule deletes the stored tokens immediately. You can also revoke Ferrule's access directly from the third-party service's connected-apps settings page.
API key integrations
Some integrations (for example, CallRail) do not use OAuth; they use long-lived API keys. You paste the key into Ferrule's dashboard, and Ferrule encrypts and stores it the same way it stores OAuth tokens.