# Organization and channels

> These endpoints describe your key, your organization and its channels. Use them to find the IDs that other endpoints take.

Canonical HTML page: https://conclude.io/doc/api/organization/
Last updated: 2026-10-27

---

**The API is in beta.** API keys are available to organizations in the beta program. Requests and responses may still change, and we tell beta customers before they do. [Contact us](https://conclude.io/contact/) to get access.

These endpoints describe your key, your organization and its channels. Use them to find the IDs that other endpoints take.

## Describe the key

`GET /v1/apiKey` · any scope

Returns the key that issued the token, and the person the token acts for. Use it to check a new key or token.

```sh
curl https://api.conclude.io/v1/apiKey -H "Authorization: Bearer $ACCESS_TOKEN"
```

```json
{
  "id": "J-1k3m5o7q9",
  "name": "Helpdesk",
  "scopes": ["connections:readwrite", "org:read"],
  "expires": "2027-10-27T00:00:00Z",
  "global": true,
  "organization": {"id": "O-2a4c6e8g", "name": "Example Corp"},
  "actsFor": {"id": "U-3b5d7f9h", "name": "Kim Lee"}
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | The key's ID. It is also its client ID. |
| `name` | string | The name the admin gave the key. |
| `scopes` | array of strings | The key's [scopes](https://conclude.io/doc/api/authentication/#scopes). |
| `expires` | time | When the key expires. |
| `global` | boolean | `true` when the key acts as Conclude. |
| `organization` | object | Your organization's `id` and `name`. |
| `actsFor` | object | The `id` and `name` of the person the token acts for. A key that acts as Conclude, used without a subject, acts for no one and has no `actsFor`. |

| Status | Code | When |
|---|---|---|
| 403 | `forbidden` | The token doesn't come from an API key. |

## Get the organization

`GET /v1/organization` · scope `org:read`

Returns your organization and its workspaces. A workspace is a Slack workspace or a Microsoft Teams tenant.

```sh
curl https://api.conclude.io/v1/organization -H "Authorization: Bearer $ACCESS_TOKEN"
```

```json
{
  "id": "O-2a4c6e8g",
  "name": "Example Corp",
  "workspaces": [
    {"id": "T-4c6e8g0i", "name": "Example", "platform": "slack", "sysID": "T04ABCDEF12"},
    {
      "id": "T-5d7f9h1j",
      "name": "Example Corp",
      "platform": "teams",
      "sysID": "72f988bf-86f1-41af-91ab-2d7cd011db47"
    }
  ]
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Your organization's ID. |
| `name` | string | Your organization's name. |
| `workspaces` | array | Your Slack workspaces and Microsoft Teams tenants. |
| `workspaces[].id` | string | The workspace's Conclude ID. |
| `workspaces[].name` | string | The workspace's name. |
| `workspaces[].platform` | string | `slack` or `teams`. |
| `workspaces[].sysID` | string | The Slack workspace ID, or the Microsoft Teams tenant ID. Use it as `sysTeamID` in [`GET /v1/findChannel`](#find-channels). |

| Status | Code | When |
|---|---|---|
| 403 | `forbidden` | The person the token acts for has no access to your organization. |

## Find channels

`GET /v1/findChannel` · scope `org:read`

Finds channels by name or by their Slack or Teams ID. It returns the Conclude channel IDs that the [Connections](https://conclude.io/doc/api/connections/) requests take.

| Parameter | Description |
|---|---|
| `name` | The channel's name. The match is exact but ignores case. A leading `#` is ignored. |
| `sysChannelID` | The Slack channel ID, such as `C07ABCDEF12`, or the Microsoft Teams channel ID, such as `19:a1b2c3@thread.tacv2`. |
| `sysTeamID` | Optional. Limits the search to one Slack workspace, one team in Microsoft Teams, or one Microsoft Teams tenant. Use the Slack workspace ID, the team's group ID, or the tenant ID. |

Give either `name` or `sysChannelID`, not both.

```sh
curl -G https://api.conclude.io/v1/findChannel \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "name=it-help"
```

```json
{
  "channels": [
    {
      "id": "C-6e8g0i2k",
      "name": "it-help",
      "platform": "slack",
      "sysID": "C07ABCDEF12",
      "private": false,
      "shared": false,
      "connected": false,
      "workspace": {"id": "T-4c6e8g0i", "name": "Example", "sysID": "T04ABCDEF12"},
      "team": {"name": "Example", "sysID": "T04ABCDEF12"}
    }
  ]
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | The channel's Conclude ID. |
| `name` | string | The channel's name. |
| `platform` | string | `slack` or `teams`. |
| `sysID` | string | The Slack or Microsoft Teams channel ID. |
| `private` | boolean | `true` for a private channel. |
| `shared` | boolean | `true` for a Slack Connect channel or a Microsoft Teams shared channel. |
| `connected` | boolean | `true` when the channel is already in a connection. |
| `workspace` | object | The Slack workspace or Microsoft Teams tenant, with its `id`, `name` and `sysID`. |
| `team` | object | The channel's team in Microsoft Teams, with its `name` and `sysID`. On Slack, it is the workspace. |

The search returns regular channels only. It leaves out direct messages, group chats, and archived or deleted channels. The results are sorted by name and are not paged. No match returns an empty list.

A search can return more than one channel:

- The same name can exist in several teams or workspaces. Add `sysTeamID` to pick one.
- In Slack Enterprise Grid, a channel shared between workspaces appears once for each workspace.

The search finds the channels that the person the token acts for can access. That means channels in teams where they have an account, and private channels where they are a member. A key that acts as Conclude, used without a subject, finds every channel, including private channels that Conclude is not in.

| Status | Code | When |
|---|---|---|
| 400 | `invalid_request` | Neither or both of `name` and `sysChannelID` are given. `param` is `name`. |
| 403 | `forbidden` | The person the token acts for has no access to your organization. |