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}| Query | Meaning |
|---|---|
search | Optional. Up to 64 characters. The best matches, on one page. |
limit | Optional. 1 to 100, default 25. |
cursor | Optional. 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.
Your server asks for a connect link
POST /workspaces/{workspaceId}/agents/{agentId}/integrations/connections| Field | Type | Rules |
|---|---|---|
app | string | Required. The app's slug from the catalogue. |
returnUrl | string | Required. An https URL of your product, up to 2,000 characters, on an allowed origin. |
label | string | Optional. 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| Parameter | Meaning |
|---|---|
connection_id | The connectionId of step 2. |
status | connected, 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
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | A missing or bad field. |
| 400 | unsupported_app | The app is github, or is not in the catalogue. |
| 402 | billing_inactive | Your subscription has ended or is paused. A past-due payment does not stop a connection. |
| 402 | plan_limit | Your plan does not include connected apps. |
| 404 | not_found | No such agent or connection. |
| 409 | conflict | The setup of the agent failed or was cancelled. |
| 422 | return_url_not_allowed | returnUrl is not https, or not on an allowed origin. |
What your customer sees
- A hosted connect page for the app, with the brand name and logo of your
account.
GET /accountshows them asbrand.nameandbrand.logoUrl. The Sokko team sets both for you. - 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.
- 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}/integrationscurl 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:falsewhen 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 isconnected,pendingornot_connected. Use it to show your customer what is left to connect. The agent object carries the same list asintegrations.
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_usersagent 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
operatoragent 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 yourreturnUrl. 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
appsCentsin the usage. - A recipe test connects no apps.