Skip to content

Credentials

Create credential connection

Create a short-lived browser URL to connect an OAuth provider or reconnect a credential. Requires workspace write access; reconnecting also requires credential Admin access. Open the URL, sign in as the acting user, complete provider authorization, then refresh List credentials. QuickBooks requires caller-managed `oauthClientConfig` for either flow. Workspace API keys return `403`; use a personal API key or scoped OAuth token. OAuth scope: `api:write`.

POST/api/v2/credentials/connections

Create a short-lived browser URL to connect an OAuth provider or reconnect a credential. Requires workspace write access; reconnecting also requires credential Admin access. Open the URL, sign in as the acting user, complete provider authorization, then refresh List credentials. QuickBooks requires caller-managed oauthClientConfig for either flow. Workspace API keys return 403; use a personal API key or scoped OAuth token.

OAuth scope: api:write.

Authentication

Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.

Send X-API-Key in the request header.

Alternatively

Send a Sim OAuth access token in Authorization: Bearer. See OAuth authentication and scopes.

Authorization: Bearer YOUR_ACCESS_TOKEN

Required scopes: api:write

OAuth flows
json
{
  "authorizationCode": {
    "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize",
    "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "scopes": {
      "api:read": "Read your workspaces, workflows, files, tables, and logs",
      "api:write": "Read, create, change, run, and delete resources in your workspaces",
      "offline_access": "Stay signed in without asking again"
    }
  }
}

OAuth scope: api:write.

Request body

Required

Provide workspaceId for every flow. For a new connection, send providerId and displayName; for a reconnect, send credentialId and retain the existing name. QuickBooks also requires oauthClientConfig for either flow; omit it for other providers.

CreateCredentialConnectionBody

Provide workspaceId for every flow. For a new connection, send providerId and displayName; for a reconnect, send credentialId and retain the existing name. QuickBooks also requires oauthClientConfig for either flow; omit it for other providers.

Schema details

Any of

Option 1value
Schema details

Any of

Option 1object
4 fields
workspaceIdstringRequired

Workspace that will own the credential.

minLength
1
maxLength
128
displayNamestringRequired

Name shown for the new credential in Sim.

minLength
1
maxLength
255
providerIdstringRequired

QuickBooks OAuth provider ID returned by credential-provider discovery.

const
quickbooks
oauthClientConfigobjectRequired

Write-only caller-managed Intuit OAuth app configuration.

4 fields
clientIdstringRequired

Client ID for the caller-managed Intuit OAuth application.

minLength
1
maxLength
255
clientSecretstringRequired

Write-only client secret for the caller-managed Intuit OAuth application.

minLength
1
maxLength
512
writeOnly
true
environmentstringRequired

Intuit company environment used for authorization and API requests.

enum
["sandbox","production"]
webhookVerifierTokenstringRequired

Write-only verifier token for webhook signatures from the caller-managed app.

minLength
1
maxLength
512
writeOnly
true

Additional properties are not allowed.

Additional properties are not allowed.

Option 2object
3 fields
workspaceIdstringRequired

Workspace that will own the credential.

minLength
1
maxLength
128
displayNamestringRequired

Name shown for the new credential in Sim.

minLength
1
maxLength
255
providerIdstringRequired

Exact OAuth provider ID returned by credential-provider discovery.

enum
["greenhouse","github-repositories","google-email","google-drive","google-docs","google-sheets","google-forms","google-calendar","google-contacts","google-ads","google-bigquery","google-tasks","google-vault","google-groups","google-chat","google-meet","vertex-ai","microsoft-ad","microsoft-dataverse","microsoft-excel","microsoft-intune","microsoft-planner","microsoft-powerbi","microsoft-teams","microsoft-word","outlook","onedrive","sharepoint","x","tiktok","confluence","jira","airtable","bitbucket","notion","clickup","linear","manageengine-sdp","monday","box","dropbox","shopify","slack","reddit","wealthbox","webflow","trello","asana","attio","calcom","docusign","pipedrive","ramp","helpscout","hubspot","apollo","linkedin","instagram","salesforce","salesforce-sandbox","zoho-desk","zoom","wordpress","spotify"]

Additional properties are not allowed.

Option 2object
3 fields
workspaceIdstringRequired

Workspace expected to own the credential.

minLength
1
maxLength
128
credentialIdstringRequired

Existing OAuth credential to reconnect in place. QuickBooks reconnects also require oauthClientConfig with the Intuit client ID, client secret, environment, and webhook verifier token.

minLength
1
maxLength
255
oauthClientConfigobject

Write-only Intuit OAuth app configuration. Required when credentialId identifies a QuickBooks credential; omit it for other providers.

4 fields
clientIdstringRequired

Client ID for the caller-managed Intuit OAuth application.

minLength
1
maxLength
255
clientSecretstringRequired

Write-only client secret for the caller-managed Intuit OAuth application.

minLength
1
maxLength
512
writeOnly
true
environmentstringRequired

Intuit company environment used for authorization and API requests.

enum
["sandbox","production"]
webhookVerifierTokenstringRequired

Write-only verifier token for webhook signatures from the caller-managed app.

minLength
1
maxLength
512
writeOnly
true

Additional properties are not allowed.

Additional properties are not allowed.

Request example 1

json
{
  "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
  "providerId": "slack",
  "displayName": "Support Slack"
}

Request example 2

json
{
  "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
  "credentialId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Request example 3

json
{
  "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
  "providerId": "quickbooks",
  "displayName": "Accounting",
  "oauthClientConfig": {
    "clientId": "YOUR_INTUIT_CLIENT_ID",
    "clientSecret": "YOUR_INTUIT_CLIENT_SECRET",
    "environment": "sandbox",
    "webhookVerifierToken": "YOUR_WEBHOOK_VERIFIER_TOKEN"
  }
}

Responses

200

A short-lived browser authorization URL.

object

Short-lived Sim browser entrypoint and its expiry.

1 field
dataobjectRequired

Response data.

3 fields
authorizationUrlstringRequired

Short-lived Sim browser URL that starts the OAuth authorization flow.

format
uri
draftIdstringRequired

ID of the pending connection behind authorizationUrl. Only the user who created it can complete it.

expiresAtstringRequired

ISO 8601 timestamp when the connection link expires.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Additional properties are not allowed.

Additional properties are not allowed.

Response example 1

json
{
  "data": {
    "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize?draftId=draft-123",
    "draftId": "draft-123",
    "expiresAt": "2026-06-20T14:17:11.000Z"
  }
}

Response headers

X-RateLimit-Limitinteger

Maximum requests allowed in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Remaininginteger

Requests remaining in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Resetstring

ISO 8601 timestamp when the current rate-limit window resets.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Was this helpful?
Suggest an edit