OAuth connections

OAuth lets you connect a provider by signing in to it, instead of pasting an API token. Tried runs the authorization code flow, stores the tokens encrypted with the connection, and refreshes them before they expire.

Providers#

Calendly and Zendesk connect with pasted credentials only.

Deployment setup Needs keys#

Each provider needs an OAuth client registered with the vendor, and its id and secret in the API's environment:

Optional per provider: <PREFIX>_OAUTH_AUTHORIZE_URL and <PREFIX>_OAUTH_TOKEN_URL override the vendor endpoints.

Register this redirect URI with every vendor app:

https://api.tried.com.au/oauth/callback

GET /oauth/providers returns the exact redirect URI for your deployment.

Without a client id, a provider uses the built-in mock OAuth provider. Its consent page says "Mock OAuth provider" and "No real account is used". Connections created through it stay in mock mode.

Connect from the dashboard#

CRM: Settings, Integrations, CRM sync, then Connect on the provider's card. After a successful connection the card shows Reconnect.

Apps: Connect app, choose the App, then Connect with HubSpot account (the label names the chosen app). For an existing app, open it and press Connect with OAuth (or Reconnect with OAuth).

Synced sources: in a knowledge base, Connect a folder, pick the provider, then Connect Google Drive (or OneDrive, Notion).

For Dynamics 365 the dashboard first asks for your organisation URL, for example https://contoso.crm.dynamics.com.

After consent, you return to the page you started from with a toast: "HubSpot connected" or "Couldn't connect HubSpot" (named after the provider), with the vendor's error.

Connect with the API#

POST /oauth/start returns the URL to send the user's browser to. Admin or developer role.

curl -X POST https://api.tried.com.au/oauth/start \
  -H "Authorization: Bearer $TRIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target": "crm", "provider": "salesforce", "options": {"login_url": "https://test.salesforce.com"}}'

{
  "authorize_url": "https://test.salesforce.com/services/oauth2/authorize?response_type=code&client_id=3MVG9...&redirect_uri=https%3A%2F%2Fapi.tried.com.au%2Foauth%2Fcallback&state=...&scope=api+refresh_token&code_challenge=...&code_challenge_method=S256",
  "mock": false,
  "provider": "salesforce",
  "pkce": true
}

After consent the vendor redirects to /oauth/callback, which stores the tokens and redirects the browser to the dashboard with query parameters:

What a successful connection creates#

Values the vendor returns with the token are kept with it: Salesforce instance_url, Zoho api_domain, GoHighLevel location_id, Notion workspace id.

Security#

• State: the state parameter is encrypted, expires after 10 minutes and can be used once.
• PKCE: S256 for the providers marked above (and always for the mock provider).
• Storage: tokens are encrypted inside the connection's credentials and never returned by the API.

Token refresh#

• Before each use, a token with less than 5 minutes left is refreshed first. Only one refresh runs per connection at a time, across API instances.
• Every minute, connections expiring within 10 minutes are refreshed in the background.
• Notion tokens do not expire and have no refresh token.

Force a refresh with POST /oauth/refresh:

curl -X POST https://api.tried.com.au/oauth/refresh \
  -H "Authorization: Bearer $TRIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target": "crm", "provider": "hubspot"}'

{ "refreshed": true, "expires_at": 1760690400000 }

Pass {"target": "app", "app_id": "app_..."} for an app. A connection that was set up with a pasted token returns 400 "This connection does not use OAuth".