Sokko Docs
Platform API

Integrations

Let your customer connect an app such as Gmail or Google Calendar to an agent, from a button in your own product.

A connected app gives an agent actions in a third-party service: read a calendar, send an email, add a row to a sheet. Your customer signs in to the app once, and the agent can then use it. The access token stays on the platform's side: neither you nor the agent ever holds it.

The connection belongs to one agent. An account connected to one agent does not work for another.

All paths below are relative to https://sokko.ai/api/v1.

The app catalogue

GET /integrations/apps
GET /integrations/apps/{slug}
QueryMeaning
searchOptional. Up to 64 characters. The best matches, on one page.
limitOptional. 1 to 100, default 25.
cursorOptional. The nextCursor of the previous page. Not used with search.

Without search, the list comes most used first.

curl "https://sokko.ai/api/v1/integrations/apps?search=calendar" \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY"
{
  "data": [
    {
      "slug": "googlecalendar",
      "name": "Google Calendar",
      "description": "Read and manage calendar events.",
      "logoUrl": "https://logos.example/googlecalendar.svg",
      "authType": "oauth"
    }
  ],
  "nextCursor": null
}

Use the slug everywhere an app is named. Show name and logoUrl in your own interface. logoUrl can be null, and description can be empty.

authType says how a person authorizes the app on the connect page: oauth (a sign-in at the app), api_key, basic, bearer_token or custom (the person types a credential).

One app cannot be connected through the API: github (and every slug that starts with github_). GitHub access is not a connected app: it works through an installation on a GitHub account, and the API has no call for that. It is not in the catalogue, GET /integrations/apps/{slug} answers 404 for it, and a connect request answers 400 unsupported_app.

Some apps (for example tiktok, snapchat and shopify) connect through Sokko's own application at that app, so their permission screen names Sokko. They are in the catalogue when they can be connected.

Errors: 400 invalid_request (a search that is too long, a bad limit or cursor), 404 not_found (no app with this slug).

The connect flow

The flow has one rule: your server asks for the link when your customer clicks, not before. The link lives about ten minutes.

Your customer clicks "Connect" in your product

Your front end calls your server. Your server holds the platform key.

POST /workspaces/{workspaceId}/agents/{agentId}/integrations/connections
FieldTypeRules
appstringRequired. The app's slug from the catalogue.
returnUrlstringRequired. An https URL of your product, up to 2,000 characters, on an allowed origin.
labelstringOptional. 1 to 60 characters. A name for this connection, for example the mailbox it is for.
curl https://sokko.ai/api/v1/workspaces/$WORKSPACE/agents/$AGENT/integrations/connections \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "googlecalendar",
    "label": "Shop calendar",
    "returnUrl": "https://app.acme.example/settings/apps"
  }'

The answer is 201:

{
  "connectionId": "d5f7a9c1-3e2b-4a6c-8d0e-1f2a3b4c5d6e",
  "connectUrl": "https://connect.example/link/lk_8sJ2mQ4x",
  "expiresAt": "2026-11-20T10:02:00.000Z"
}

Store connectionId with your customer's record. connectUrl is on the host of the connection service the platform uses, not on a host of yours and not on sokko.ai.

Your server sends the browser to connectUrl

Redirect the browser, or open the link in a new tab. Do it at once: after expiresAt the link no longer works, and you ask for a new one.

The browser comes back to your returnUrl

The platform redirects the browser to your returnUrl and adds two query parameters:

https://app.acme.example/settings/apps?connection_id=d5f7a9c1-3e2b-4a6c-8d0e-1f2a3b4c5d6e&status=connected
ParameterMeaning
connection_idThe connectionId of step 2.
statusconnected, pending (the app has not confirmed yet) or error.

Your server reads the status

A query parameter can be typed by anyone. Do not trust it: read the connection with your key before you show "connected".

GET /workspaces/{workspaceId}/agents/{agentId}/integrations/connections/{connectionId}
curl https://sokko.ai/api/v1/workspaces/$WORKSPACE/agents/$AGENT/integrations/connections/d5f7a9c1-3e2b-4a6c-8d0e-1f2a3b4c5d6e \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY"
{
  "id": "d5f7a9c1-3e2b-4a6c-8d0e-1f2a3b4c5d6e",
  "app": "googlecalendar",
  "label": "Shop calendar",
  "status": "connected",
  "createdAt": "2026-11-20T09:52:00.412Z"
}

status is pending, connected or failed. Reading a pending connection checks it again with the app, so a short poll after the return is enough. You can also wait for the event connection.active or connection.failed. See Webhooks.

The agent can use the app as soon as the connection is connected. No restart is needed.

You can ask for a link as soon as the agent exists, also while it is still preparing or provisioning. The connections are attached to the agent when it starts. If the agent's setup fails or you delete the agent first, those connections are revoked, and a new connect request for that agent answers 409 conflict.

The return URL and its allowlist

returnUrl must be on an origin that your account allows. An origin is the scheme, the host and the port, for example https://app.acme.example. Your account holds up to 20 origins, each https. The Sokko team sets the list: send them the origins of your production and staging front ends.

A returnUrl on any other origin answers 422 return_url_not_allowed, so the browser can only come back to a page of yours.

You can put your own state in the returnUrl, as a path or a query parameter. It comes back unchanged, with the two parameters added.

Errors

StatusCodeWhen
400invalid_requestA missing or bad field.
400unsupported_appThe app is github, or is not in the catalogue.
402billing_inactiveYour subscription has ended or is paused. A past-due payment does not stop a connection.
402plan_limitYour plan does not include connected apps.
404not_foundNo such agent or connection.
409conflictThe setup of the agent failed or was cancelled.
422return_url_not_allowedreturnUrl is not https, or not on an allowed origin.

What your customer sees

  1. A hosted connect page for the app, with the brand name and logo of your account. GET /account shows them as brand.name and brand.logoUrl. The Sokko team sets both for you.
  2. The app's own sign-in and permission screens. For a Google app, for example, that is Google's account chooser and its list of permissions.
  3. Your returnUrl.

Your customer is never shown a Sokko page and is never asked for a Sokko account. Two things are not in your brand:

  • The connect page is on the host of the connection service the platform uses, and so are the logos of the catalogue.
  • On the permission screen of most apps, the application that asks for access carries the name of that connection service, not yours. The API has no way to use an application of your own for the sign-in.

If the browser cannot be sent back to your returnUrl (for example because its origin left your allowlist in the meantime), your customer sees a plain page with one sentence and no name on it.

Read an agent's integrations

GET /workspaces/{workspaceId}/agents/{agentId}/integrations
curl https://sokko.ai/api/v1/workspaces/$WORKSPACE/agents/$AGENT/integrations \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY"
{
  "enabled": true,
  "connections": [
    {
      "id": "d5f7a9c1-3e2b-4a6c-8d0e-1f2a3b4c5d6e",
      "app": "googlecalendar",
      "label": "Shop calendar",
      "status": "connected",
      "createdAt": "2026-11-20T09:52:00.412Z"
    }
  ],
  "required": [
    { "app": "googlecalendar", "required": true, "status": "connected" },
    { "app": "gmail", "required": false, "status": "not_connected" }
  ]
}
  • enabled: false when connected apps are switched off for the agent. An agent you create through the API has them on.
  • connections: every connection of the agent, oldest first, with its status.
  • required: for an agent made from a recipe, the apps the recipe names, whether each is required, and whether it is connected, pending or not_connected. Use it to show your customer what is left to connect. The agent object carries the same list as integrations.

Errors: 404 not_found.

Disconnect

DELETE /workspaces/{workspaceId}/agents/{agentId}/integrations/connections/{connectionId}
curl -X DELETE https://sokko.ai/api/v1/workspaces/$WORKSPACE/agents/$AGENT/integrations/connections/d5f7a9c1-3e2b-4a6c-8d0e-1f2a3b4c5d6e \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY"
{ "id": "d5f7a9c1-3e2b-4a6c-8d0e-1f2a3b4c5d6e", "deleted": true }

The connection is revoked, and the agent can no longer use that account. To connect it again, run the connect flow again.

Deleting the agent or the workspace also revokes its connections.

Errors: 404 not_found.

Good to know

  • An end_users agent cannot start a connection from a conversation. If an end user asks the agent to "connect my calendar", nothing happens until your product runs the connect flow.
  • An operator agent can offer a connect link in a conversation, like any Sokko agent. That link is not this connect flow: it and its label name Sokko, and the browser does not return to your returnUrl. To keep the flow in your product, run the connect flow yourself.
  • The actions an agent runs in a connected app are paid from the workspace's credits. They show as appsCents in the usage.
  • A recipe test connects no apps.

On this page