Skip to main content
Connections give a tenant user’s agents authenticated access to 1,000+ third-party apps (Gmail, Slack, GitHub, Stripe, Notion, …). Every connection is per-user and gated by the user’s Account Kit. Naive keeps a local mirror of connection status so reads are cheap; execute-time auth always goes through the connections provider.

​
CLI First

naive connections list --user alice
naive connections connect gmail --user alice
naive connections execute gmail GMAIL_SEND_EMAIL --user alice --args '{"recipient_email":"lead@co.com","subject":"Hi","body":"..."}'

​
Tools

ToolTypeDescription
connections_listCoreList apps available to a user (filtered by their Account Kit) with connection status
connections_connectedCoreList the user’s active/expired connections (from the mirror)
connections_connectCoreStart a connect flow — returns a hosted redirect link
connections_toolsCoreList the tools an app exposes
connections_executeCoreExecute a specific tool for the user
connections_disconnectManagementDisconnect (optionally purge) an app for the user

​
Connecting an App

connect returns a hosted redirectUrl. Send the user there; once they finish auth the connection becomes ACTIVE. This is a sensitive action and may require approval depending on the Account Kit. 
curl -X POST https://api.usenaive.ai/v1/users/{user_id}/connections/connect \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "toolkit": "gmail", "callback_url": "https://myapp.com/oauth/callback" }'
Response: 
{
  "status": "INITIATED",
  "toolkit": "gmail",
  "redirectUrl": "https://connect.example.com/link/lk_xxx",
  "connectedAccountId": "ca_xxx"
}

​
Parameters

ParamTypeRequiredDescription
toolkitstringYesApp slug (e.g. gmail, slack, stripe) — see GET /v1/toolkits
callback_urlstringNoWhere the user is returned after auth

​
Executing a Tool

Once connected, execute any of the app’s tools: 
curl -X POST https://api.usenaive.ai/v1/users/{user_id}/connections/gmail/execute \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "tool": "GMAIL_SEND_EMAIL", "arguments": { "recipient_email": "lead@co.com", "subject": "Hi", "body": "..." } }'

​
Listing & Status

# Apps available to the user (filtered by their Account Kit) + connection status
curl https://api.usenaive.ai/v1/users/{user_id}/connections \
  -H "Authorization: Bearer nv_sk_your_key"

# Just the user's active/expired connections (cheap mirror read)
curl https://api.usenaive.ai/v1/users/{user_id}/connections/connected \
  -H "Authorization: Bearer nv_sk_your_key"
Connection status is read from Naive’s local mirror; INITIATED rows older than ~10s are refreshed before responding. See Connection status.

​
Error Handling

ErrorCauseRecovery
feature_not_configured3rd-party connections aren’t enabled on the workspaceContact support to enable them
forbiddenThe user’s Account Kit doesn’t permit this appAdjust the kit’s allow/block list
pending_approval (202)The connect was gated for human approvalApprove via the Approvals queue
not_foundInvalid user_idUse GET /v1/users for valid ids

​
Typical Workflow

Agent needs to email a lead from Alice's Gmail
    │
    ├─ GET  /v1/users/alice/connections?search=gmail   → Is Gmail available + connected?
    │
    ├─ POST /v1/users/alice/connections/connect        → Not connected → get redirectUrl
    │   { toolkit: "gmail" }                              (send Alice to finish OAuth)
    │
    ├─ GET  /v1/users/alice/connections/connected      → status: ACTIVE ✓
    │
    └─ POST /v1/users/alice/connections/gmail/execute  → Send the email
        { tool: "GMAIL_SEND_EMAIL", arguments: {...} }