Skip to content
TriedDocs
Integrations

Start OAuth

Get a vendor authorize URL that connects a CRM, an integration app or a knowledge base source with OAuth.

POSThttps://api.tried.com.au/oauth/start

Needs keys Real OAuth needs the vendor's client ID and secret on the server. Without them authorize_url points at the built-in mock OAuth provider, and the connection it creates stays in mock mode.

Returns an authorize_url to open in the user's browser. The user signs in to the vendor and approves access. The vendor then redirects to Tried's callback, which exchanges the code, stores the encrypted tokens and sends the browser on to the dashboard. Tokens are refreshed automatically before they expire.

Request#

Field Type Required Description
target string Yes crm, app or kb_sync.
provider string Yes crm: hubspot, salesforce, dynamics365, zoho, gohighlevel. app: the same plus cal_com. kb_sync: google_drive, onedrive, notion.
app_id string No app only: reconnect this existing app. It must have the same type as provider. Without it, a new app is created on success.
name string No app only: name for the new app, up to 80 characters. Defaults to the provider.
knowledge_base_id string For a new kb_sync Knowledge base that receives the synced documents.
sync_id string No kb_sync only: reconnect this existing synced source instead of creating one.
sync_config object No kb_sync only. String values: folder_id (required for Google Drive), drive_id and folder_id (OneDrive), page_id (required for Notion). Default {}.
options object No Per-connection vendor options. Default {}.
options.instance_url string (URL) Dynamics 365 Your Dynamics org URL, for example https://acme.crm6.dynamics.com.
options.tenant string No Microsoft tenant for Dynamics 365 and OneDrive. Letters, digits, _, . and -, up to 100 characters.
options.login_url string (URL) No Salesforce login host, for example https://test.salesforce.com for a sandbox.
options.accounts_url string (URL) No Zoho accounts host for your data centre, for example https://accounts.zoho.com.au.
return_to string No Dashboard path to land on afterwards. Must start with /. Default /settings/integrations (/knowledge-base for kb_sync).

Example request#

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" } }'
const res = await fetch("https://api.tried.com.au/oauth/start", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRIED_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    target: "crm",
    provider: "salesforce",
    options: { login_url: "https://test.salesforce.com" },
  }),
});
const { authorize_url } = await res.json();
import os, requests

res = requests.post(
    "https://api.tried.com.au/oauth/start",
    headers={"Authorization": f"Bearer {os.environ['TRIED_API_KEY']}"},
    json={
        "target": "crm",
        "provider": "salesforce",
        "options": {"login_url": "https://test.salesforce.com"},
    },
)
authorize_url = res.json()["authorize_url"]

Response#

200 OK

{
  "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
}
Field Type Description
authorize_url string Open it in the user's browser. The state it carries is encrypted, single-use and valid for 10 minutes.
mock boolean true when the URL points at the mock OAuth provider.
pkce boolean Whether the flow uses PKCE (S256).

After the user approves#

The callback stores the tokens and redirects the browser to the dashboard at return_to with oauth=success&provider=<provider> added. For target: app it also adds app_id. For kb_sync it adds sync_id and knowledge_base_id and starts the first sync. On failure it adds oauth=error and a message.

  • crm: creates or updates the workspace's connection for that CRM and enables it. Read it with Get CRM config.
  • app: updates the app named by app_id, or creates a new one. Read it with Get app.

Errors#

Status When
400 Body fails validation, <provider> cannot be used for <target> (use ...), dynamics365 needs options.instance_url, App <id> is a <type> app, knowledge_base_id is required, sync_config.folder_id is required, sync_config.page_id is required, or Sync <id> is a <provider> sync.
401 Missing or invalid API key.
403 The key's IP allowlist or scopes reject the request. This route needs the admin scope. Dashboard users need the admin or developer role.
404 App <id> not found, Knowledge base <id> not found or Sync <id> not found.
429 Rate limit exceeded. See Rate limits.

See Errors for the body format.