Connecting an app that uses OAuth

Most business apps do not hand out a key you can paste once. They give you an access token that expires in about an hour, plus a long-lived refresh token you exchange for a new one. Paste the access token into an API-key credential and the tool works until lunchtime, then fails in the middle of a customer conversation.

The oauth2 credential type is for those. You store the refresh token; Decibyl mints an access token when a call needs one, caches it until it expires, and mints another. Nothing to rotate by hand.

What you need from the vendor

Four things, from the app’s own developer console:

Field	Where it comes from
token_url	The vendor’s token endpoint. Must be https://.
client_id	Your OAuth app’s id.
client_secret	Your OAuth app’s secret.
refresh_token	From your first authorisation, with the scopes the agent needs.

Two optional fields cover vendors that differ:

Field	Default	Use it when
header_prefix	Bearer	The vendor uses another scheme. Zoho needs Zoho-oauthtoken.
header_name	Authorization	The vendor reads the token from a different header.
scope	(none)	The vendor requires a scope on refresh as well as on grant.

Zoho CRM

Zoho is the one that catches people out: it rejects Bearer and wants its own scheme. Set header_prefix and it works like any other.

{
  "token_url": "https://accounts.zoho.in/oauth/v2/token",
  "client_id": "1000.XXXXXXXX",
  "client_secret": "...",
  "refresh_token": "1000.yyyy.zzzz",
  "header_prefix": "Zoho-oauthtoken"
}

Use the datacentre your account lives in — accounts.zoho.in for India, accounts.zoho.com for the US. The wrong one returns invalid_client and looks exactly like a bad secret.

HubSpot, Salesforce, Google

These use the default Bearer, so only the four required fields are needed.

{
  "token_url": "https://api.hubapi.com/oauth/v1/token",
  "client_id": "...",
  "client_secret": "...",
  "refresh_token": "..."
}

Then point a tool at it

The credential is the authentication; the tool is the call. Create an HTTP API tool at /tools, set the method and the vendor’s endpoint URL, and reference the credential by its credential_uuid. Attach the tool to the agent node that should be able to use it.

The same credential works for a post-call webhook, a pre-call fetch, and a transfer resolver — anywhere a credential can be attached.

What happens on a live call

• The first tool call that needs a token exchanges the refresh token once.
• Every later call reuses the cached token until a minute before it expires.
• Concurrent calls on one agent share a single exchange rather than opening one each — some vendors invalidate the previous token on every refresh, so stampeding would leave most of them holding dead tokens.
• A refreshed token is written back to the credential, so other workers reuse it.

When it does not work

The credential is refused at creation if any of the four required fields is blank, or if token_url is not https://. The refresh token and client secret are POSTed to that URL on every exchange, so plain HTTP would put both on the wire.

A tool reports an auth error mid-call. The message names the HTTP status the token endpoint returned and never the secret. invalid_client usually means the wrong datacentre or a mistyped secret; invalid_grant usually means the refresh token has been revoked, which happens when someone re-authorises the app or removes it from the connected-apps list. Re-authorise and update the credential.

Everything 401s but the credential looks right. Check header_prefix. A Zoho credential sending Bearer fails every request with a message that says nothing about the scheme.