Connections and installation

All paths on this page are relative to https://inkbox.ai/api/v1/slack. One identity owns a dedicated Slack app created in a workspace your organization configured. The app stays bound to that workspace. Each connection belongs to that identity and carries its own status, granted permissions, and retained archive. Apps created through Inkbox use the identity’s name, description, and avatar. Later profile changes sync in the background without reconnecting; removing the avatar restores the Inkbox icon. To use another workspace, save its configuration credentials and choose it for a different identity app. Enterprise organization-wide installations are not supported.

List connections

GET /connections?identity_id={identity_id}

identity_id is a required Inkbox identity UUID. Organization admin keys and the Console can list the organization’s connections. A claimed agent key can list only its own identity’s connections.

Response (200)

{
  "connections": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "identity_id": "11111111-1111-4111-8111-111111111111",
      "workspace_id": "T0123456789",
      "workspace_name": "Example workspace",
      "bot_user_id": "U0123456789",
      "status": "connected",
      "scopes": ["chat:write", "channels:history"],
      "created_at": "2026-09-16T10:00:00Z"
    }
  ],
  "installation_available": true,
  "application_created": true,
  "setup": {"status": "ready", "retry_at": null, "error_code": null, "provisioning_workspace_id": "44444444-4444-4444-8444-444444444444"},
  "provisioning_workspace": {
    "id": "44444444-4444-4444-8444-444444444444",
    "workspace_id": "T0123456789",
    "workspace_name": "Example workspace",
    "user_id": "U0123456789",
    "status": "ready",
    "token_expires_at": "2026-10-01T12:00:00Z",
    "created_at": "2026-10-01T00:00:00Z",
    "updated_at": "2026-10-01T00:00:00Z"
  }
}

The example scopes list is illustrative, not the complete permission set. Inspect the actual connection.

Field	Type	Meaning
`connections`	array	All visible connections for the identity, including disconnected ones
`installation_available`	boolean	Whether new connection setup is available; preparation may still be pending. Does not grant management permission
`application_created`	boolean	Whether the identity has a created Slack app, independently of its connection status
`setup`	object or null	App preparation status, described below
`provisioning_workspace`	object or null	Saved workspace metadata selected for this app; never includes tokens
`connections[].id`	UUID	Connection ID used in live API requests
`connections[].identity_id`	UUID	Owning Inkbox identity
`connections[].workspace_id`	string	Slack workspace ID
`connections[].workspace_name`	string	Workspace display name
`connections[].bot_user_id`	string	Bot user in this workspace
`connections[].status`	string	`connected`, `disconnected`, or `reauthorization_required`
`connections[].scopes`	string array	Granted Slack permissions
`connections[].created_at`	timestamp	When this connection was created

You can list connections for a paused identity. Its installation_available is false. Live Slack operations require an active identity and a connected workspace. application_created stays true when the identity is paused or every workspace is disconnected; those actions preserve the app. Older API responses may omit the field; current SDKs default it to false when absent.

Save a provisioning workspace

POST /provisioning-workspaces

Any organization member, organization admin API key, or claimed agent API key can supply both Slack app-configuration tokens for the workspace where the app should be created. Use Your App Configuration Tokens on Slack apps page and select the intended workspace. These are app-configuration credentials, not a bot token or password.

Field	Type	Required
`access_token`	string	Yes
`refresh_token`	string	Yes

The server verifies the workspace and saves the credentials for reuse by your organization. A subsequent save for the same verified workspace updates its credentials. Do not log the input. Responses never return either token. The 200 response contains:

Field	Type	Meaning
`id`	UUID	Saved provisioning-workspace ID used when preparing an app
`workspace_id`	string	Verified Slack workspace ID, starting with `T`
`workspace_name`	string	Verified workspace name
`user_id`	string	Account associated with the configuration credentials
`status`	string	`ready` or `reauthorization_required`
`token_expires_at`	timestamp or null	Current access-token expiration when known
`created_at`, `updated_at`	timestamp	Saved workspace timestamps

List saved provisioning workspaces

GET /provisioning-workspaces

Any organization member in the Console, organization admin API key, or claimed agent key can read saved metadata for their organization. Unclaimed keys cannot. Returns 200 with {"workspaces": [...]} using the metadata above. Select the desired entry’s id; this UUID is different from its Slack workspace_id.

Prepare the app

POST /applications/setup

Requires an organization member in the Console, organization admin API key, or claimed agent key and an active identity. Claimed keys can prepare only their own identity’s app; the selected workspace must belong to their organization. Send:

{
  "identity_id": "11111111-1111-4111-8111-111111111111",
  "provisioning_workspace_id": "44444444-4444-4444-8444-444444444444"
}

The request starts or reuses preparation in that saved workspace and returns promptly. Repeated requests do not create duplicate apps. No identity update or separate enablement step is required. Returns 202 while pending, with Retry-After, or 200 for another state:

Field	Type	Meaning
`status`	string	`not_started`, `needs_credentials`, `pending`, `ready`, `failed`, or `unavailable`
`retry_at`	timestamp or null	Next scheduled attempt when known; not a completion estimate
`error_code`	string or null	`credentials_required`, `setup_failed`, `outcome_unknown`, or `quota_exceeded` when attention is needed
`provisioning_workspace_id`	UUID or null	Selected saved workspace

While pending, preparation continues without keeping the browser open. Read GET /connections?identity_id=... every few seconds to follow setup; bound your wait and resume later if needed. The Console checks automatically. When ready, start browser installation. needs_credentials requires saving valid configuration credentials before retrying. Do not blindly retry outcome_unknown; contact support to reconcile the earlier attempt. Reading status never restarts setup.

setup = inkbox.slack.start_setup(identity_id, provisioning_workspace_id)
current = inkbox.slack.list_connections(identity_id)

const setup = await inkbox.slack.startSetup(identityId, provisioningWorkspaceId);
const current = await inkbox.slack.listConnections(identityId);

inkbox slack setup start --identity-id 11111111-1111-4111-8111-111111111111 \
  --provisioning-workspace-id 44444444-4444-4444-8444-444444444444

An app cannot be moved to a different saved workspace by calling setup again. Save another workspace’s credentials for a different identity app instead.

Start browser installation

POST /installations

Requires an organization member in the Console, organization admin API key, or the identity’s claimed agent key. Use Add to Slack (or Reconnect to Slack for an existing connection) in the Inkbox Console, or request an installation link from the API and open the returned authorization_url in a browser. Too many active installation attempts return 429; honor Retry-After. If no provisioning workspace is selected, this request returns 409 with detail.code: "credentials_required"; save workspace credentials and prepare the app first. Once the workspace is selected, unfinished preparation returns 409 with detail.code: "slack_setup_pending" and Retry-After. No authorization URL is issued. Follow preparation status, then retry when ready. A setup failure returns 409 with detail.code: "slack_setup_failed"; use the preparation recovery guidance instead of repeatedly requesting installation URLs. Changed app configuration can also return 409, and unavailable setup returns 503; see common errors.

Field	Type	Required	Meaning
`identity_id`	UUID	Yes	Identity to connect
`workspace_id`	string or null	No	Optional expected workspace; must match the app’s saved workspace. Installation always targets that workspace. Starts with `T`, followed by uppercase letters or digits, up to 64 characters total
`return_url`	string or null	No	Approved Console completion URL, up to 2,048 characters. The path must be exactly `/console/slack/complete`. Omit it or send `null` to use the default Console completion page

Request body

{
  "identity_id": "11111111-1111-4111-8111-111111111111",
  "workspace_id": "T0123456789",
  "return_url": "https://inkbox.ai/console/slack/complete"
}

Use an HTTPS return_url without a query string or fragment. For browser requests, its origin must match the request’s Origin. Invalid completion URLs return 422.

Response (200)

Field	Type	Meaning
`authorization_url`	string	Browser URL that continues installation
`expires_at`	timestamp	Installation flow expiration

For a server-side request without an Origin header, or a browser request from a different origin, authorization_url is a browser handoff link. Open it in a browser to establish the installation session and continue to Slack. You do not need to copy a cookie out of the API response. For a same-origin Console request, the initiating browser receives the session cookie directly. Complete the approval in that browser. Treat the returned URL as a secret installation capability. It expires after 15 minutes. Do not put it in logs, analytics, or public pages. Use expires_at rather than assuming an old link still works. After approval, the browser returns to the Console’s completion page or the approved return_url you supplied. Arbitrary websites and local URLs are not supported return destinations. Cancellation and failure do not establish a connection. List connections again to confirm the resulting workspace and status. For an existing connection missing newly requested profile permissions, start installation again for the same identity and workspace to approve the new permissions. Existing messaging remains available while you decide. Reauthorization applies to the selected workspace only. Previously queued events are not restored by reconnecting. Workspace installation still requires adding the bot to each chosen channel.

Disconnect a workspace

POST /connections/{connection_id}/disconnect

connection_id is a UUID. No request body is required. This endpoint requires an organization admin API key or an organization member’s Console session; claimed agent keys cannot disconnect a workspace. It remains available when the identity is paused.

Response (200)

Returns the connection object described above, with status: "disconnected". Disconnect removes Inkbox’s authority to use this connection. It does not uninstall the Slack app or revoke its installation in Slack. Disconnect stops capture through this connection and makes the connection’s retained content unavailable while deletion completes. Reconnecting resumes capture automatically but does not restore that content. Request backfills explicitly as needed. Pending installation attempts for the disconnected workspace are cancelled. A workspace administrator can uninstall the app separately in Slack.

Agent signup API

Agent identity API

Agent2Agent API

Message retries

Mail API

Phone API

iMessage API

Slack API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

Connections and installation

List connections

Response (200)

Save a provisioning workspace

List saved provisioning workspaces

Prepare the app

Start browser installation

Request body

Response (200)

Disconnect a workspace

Response (200)

​List connections

​Response (200)

​Save a provisioning workspace

​List saved provisioning workspaces

​Prepare the app

​Start browser installation

​Request body

​Response (200)

​Disconnect a workspace

​Response (200)

List connections

Response (200)

Save a provisioning workspace

List saved provisioning workspaces

Prepare the app

Start browser installation

Request body

Response (200)

Disconnect a workspace

Response (200)