> ## Documentation Index
> Fetch the complete documentation index at: https://inkbox.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connections and installation

> Save workspace configuration credentials, prepare an identity app, and manage its Slack connection

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

```text theme={null}
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)

```json theme={null}
{
  "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

```text theme={null}
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](https://api.slack.com/apps) 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

```text theme={null}
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

```text theme={null}
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:

```json theme={null}
{
  "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.

```python theme={null}
setup = inkbox.slack.start_setup(identity_id, provisioning_workspace_id)
current = inkbox.slack.list_connections(identity_id)
```

```typescript theme={null}
const setup = await inkbox.slack.startSetup(identityId, provisioningWorkspaceId);
const current = await inkbox.slack.listConnections(identityId);
```

```bash theme={null}
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

```text theme={null}
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](https://inkbox.ai/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](/docs/api/slack/connections#prepare-the-app), then retry when `ready`.

A setup failure returns `409` with `detail.code: "slack_setup_failed"`; use the [preparation recovery guidance](#prepare-the-app) instead of repeatedly requesting installation URLs. Changed app configuration can also return `409`, and unavailable setup returns `503`; see [common errors](/docs/api/slack#common-errors-and-limits).

| 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

```json theme={null}
{
  "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

```text theme={null}
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.