Skip to main content
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 for an existing identity, remove its current app, then connect again with the workspace you choose. You can also use a different identity app. Enterprise organization-wide installations are not supported.

List connections

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)

The example scopes list is illustrative, not the complete permission set. Inspect the actual connection. 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.

List available connections

Use an organization admin API key or the Console to list connected Slack accounts across your organization. Claimed agent keys cannot use this endpoint. Add the optional identity_id query parameter to restrict the list to one identity. The response contains connections, with id, identity_id, agent_handle, workspace_id, and workspace_name on each entry. Only active identities with ready apps and connected accounts are included. An empty list means none match. This returns saved connection metadata without calling Slack. It does not check current Slack availability or import contacts. Use the per-identity connection endpoint above for setup details and connection status.

Save a provisioning workspace

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. The server verifies the workspace and Slack creator, then saves the credentials for reuse by your organization. Renewing the same workspace and creator updates that saved record without changing its id. A different creator in the same workspace receives a separate saved record and id; existing apps keep their original record and credentials. Select the returned id when preparing a new app. Generate a separate token pair for each Inkbox organization. Do not log the input. Responses never return either token. The 200 response contains:

List saved 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. Multiple entries can have that same workspace ID but different creator IDs and saved record IDs. The Console labels choices as Workspace — @account, falling back to the Slack user ID when a cached name is missing. Older records can have user_name: null. Names are display metadata; select the intended saved record rather than matching a workspace name alone. Renew the original creator’s record to update credentials for its existing apps.

Prepare the app

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:
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: 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.
An existing app cannot move to a different saved workspace by calling setup again. Remove it first, then explicitly prepare a fresh app in the workspace you choose.

Remove the app

The SDK and CLI removal examples require version 0.7.23 or later.
In the Inkbox Console Slack page, open Slack Apps, and select the trash icon on the agent’s row. In Remove Slack app, type the agent’s @handle to confirm, then select Remove app. You can also use the API with an organization admin API key. Claimed agent keys cannot remove apps or read removal progress. Removal disconnects the app from the Inkbox identity. It does not create or prepare another app. Use it when an app was deleted, is broken, or is no longer needed. To authorize the same existing app again, use browser installation instead. The previous connection and its Slack messages are no longer accessible through Inkbox. Removal does not delete the Inkbox identity or change its other channels. It does not erase your agent runtime’s existing conversation memory. Read application_generation from List connections, then send: Removal always attempts permanent deletion of the old app from Slack. If the app is confirmed already deleted, deletion succeeds without further action. A credential error, permission error, or timeout does not establish that an app was deleted. The deletion outcome does not block separate fresh setup. The removal request returns 202 with: The app is removed from Inkbox independently of remote deletion from Slack. Do not interpret status: removed as confirmation that the remote app was deleted. Read GET /applications/removals/{operation_id} every few seconds with a bounded wait to follow remote deletion. This read reports only the removal operation, not any app you create later. If a removal request times out, retry with the same request ID and identical arguments; do not create a new request ID. A stale application generation or conflicting retry returns 409. Unfinished app setup, active setup/profile work, or token refresh can also return 409. Honor Retry-After when supplied; otherwise inspect setup before retrying. Poll while deletion_status is pending, even if deletion_error_code contains credentials_busy. The error field alone does not mean the operation is final. failed and unknown are final for that operation; replaying its request does not attempt remote deletion again. Check the original app in Slack app management with its original creator’s access and delete it there if needed. Verify it is the old app rather than a newly created one. These outcomes do not block fresh setup. not_requested means remote deletion was not requested for that receipt. Retrying an earlier request ID preserves its original result; it does not start another deletion attempt.

Connect again when ready

Removal leaves the identity without a Slack app or selected provisioning_workspace_id. The connection list reports application_created: false, while application_generation stays non-null and advances. That new generation is not proof an app exists and must not replace the saved generation when retrying the removal; poll its saved operation ID instead. For an active identity, the connection list reports setup.status: needs_credentials; this does not mean saved credentials are invalid. A paused identity reports unavailable; resume it before fresh setup. To connect again on the Console Slack page, select Enable Slack, choose the same agent, and select Continue. In Set up Slack, the first ready saved workspace is selected by default. Choose a saved workspace, or select Connect another workspace and supply its app-configuration credentials. If no workspace is saved, supply credentials directly. Select Continue to prepare the fresh app, then Add to Slack once setup is ready to authorize it. The new app can use a different workspace. Other identities’ apps are unchanged. With the API or SDK, select or save a workspace, then explicitly prepare the app using its saved workspace ID. When setup is ready, start browser installation to authorize it. Invite the new bot to the channels it should use. It does not inherit the old bot’s direct messages or channel access. Existing identity webhook subscriptions do not need recreating.

Start browser installation

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.

Request body

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)

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 or custom emoji 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

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.