How to

Keys and tokens Beta

On this page

Your tool signs in to the API with an API key. It exchanges the key for an access token and sends the token with every request. This page is for the admin who issues the key and the developer who builds the tool.

Issue an API key

You need to be an admin of your organization, and your organization needs a trial, Pro or Enterprise plan. A key keeps working when your organization moves to another plan.

  1. Open Admin console > Account > API keys . The page appears only for organizations in the beta program.
  2. Click Issue new key.
  3. Enter a Name that says which tool uses the key.
  4. Choose when the key expires. A key lasts at most ten years.
  5. Choose what the key can do. Full access (admin) covers every area, including areas the API adds later. Choose what the key can do lets you pick scopes.
  6. If Conclude has given you the role for it, choose who the key acts as. See Who a key acts as.
  7. Copy the Client ID and the Client secret.

Conclude shows the secret only once and stores only a hash of it. Keep the secret in your tool’s secret store. The dialog also shows a curl command that tries the key.

An organization can have at most 20 keys that aren’t revoked. Expired keys count too, so revoke them to make room.

Who a key acts as

A key always acts as someone. Conclude checks every request against that person’s access.

Acts as you. The key acts as the admin who issued it. It never reaches more than that admin can. If the admin loses a role, the key loses it too. Use this kind of key for a tool that works for you. Everyone who uses the tool then acts as you.

Acts as Conclude, for many people. The key acts as Conclude. It reaches only the channels that Conclude reaches. Use it for a tool that many people use, such as a helpdesk system. Only people who have the role from Conclude can issue these keys. Contact us to get the role. Every admin of your organization is told when such a key is issued.

A key that acts as Conclude can name a person when it asks for a token. This person is the token’s subject, and the token acts for them:

  • Conclude checks the subject’s access to each channel. To be connected, the channel must also be one that Conclude reaches
  • The key’s scopes stand in for the subject’s permissions. The tool can connect channels for a person who has no Connect channels permission
  • To change a connection or a chat, the token needs a subject
  • Without a subject, the token can read connections, chats and the audit log, and start chats between the people it names. It can also find every channel by name, including private channels that Conclude is not in. A tool can then find a channel before Conclude is added to it

Conclude can’t check that the person asked for the change. Your tool vouches for that. The audit log records the key with each change.

Channels Conclude reaches

A key that acts as Conclude reaches a channel when:

  • On Slack, the channel is public and not shared, or Conclude was added to it
  • In Microsoft Teams, the Conclude app is installed in the team, and the channel is a standard channel or Conclude was added to it. A chat needs the Conclude app in the chat

Scopes

Scopes limit what a key can do. A readwrite scope includes the read scope of the same area. You choose the scopes when you issue the key. To change them, issue a new key.

ScopeCoversEndpoints today
org:readYour organization, its workspaces and its channelsGET /v1/organization, GET /v1/findChannel
users:readThe people in your organizationGET /v1/findUser
connections:readConnections between channelsList and get connections
connections:readwriteConnections between channelsEvery request on the Connections page
chats:readChats and the bridges you can chat overList and get chats, list bridges and their chat users
chats:readwriteChats and the bridges you can chat overEvery request on the Chats page
audit:readThe audit logGET /v1/auditEvents
adminEvery area, including areas the API adds laterEvery endpoint

GET /v1/apiKey works with any scope.

The dialog also offers these scopes: users:readwrite, activities:read, activities:readwrite, knowledge:read, knowledge:readwrite, agents:read, agents:readwrite, apps:read, apps:readwrite and stats:read. No endpoint uses them yet. They are for areas the API adds later.

Get an access token

POST /v1/oauth/token

This endpoint follows the OAuth 2.0 client credentials grant (RFC 6749), which most OAuth libraries support. Send the request as application/x-www-form-urlencoded or as JSON. Send the client ID and secret either in the body or with HTTP Basic authentication. With HTTP Basic, the body can repeat the same client_id, but not the secret.

FieldTypeRequiredDescription
grant_typestringYesAlways client_credentials.
client_idstringYes, unless you use HTTP BasicThe key’s client ID, which starts with J-.
client_secretstringYes, unless you use HTTP BasicThe key’s client secret.
subjectstringNoOnly for a key that acts as Conclude. The Slack user ID, or the Microsoft Teams user’s object ID in Entra ID, of the person the token acts for. The person needs an active account in one of your organization’s workspaces.

Conclude ignores a scope field. A token always has all of the key’s scopes.

curl https://api.conclude.io/v1/oauth/token \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET" \
  -d subject=U07ABCDEF12

The response is 200:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "connections:readwrite org:read"
}
FieldDescription
access_tokenThe token. Treat it as opaque.
token_typeAlways Bearer.
expires_inSeconds until the token expires.
scopeThe key’s scopes, separated by spaces.

Use the token

Send the token in the Authorization header:

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

Conclude accepts the token only on api.conclude.io. A token lasts one hour, and there is no refresh token. Keep the token and reuse it until it expires, then ask for a new one. With subjects, keep one token for each person.

Token errors

Errors from this endpoint use the OAuth error body, not the API’s error body:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}
StatuserrorWhen
400invalid_requestThe body is not form data or JSON, is larger than 4 KB, or has no grant_type. The request sends the secret both ways, or a body client_id that differs from the HTTP Basic one. The HTTP Basic credentials are not form-encoded. The subject is not an active user in your organization.
400unsupported_grant_typegrant_type is not client_credentials.
400unauthorized_clientA key that acts as its owner named a subject.
401invalid_clientThe client ID or secret is wrong, or the key is revoked or expired. Also when the key acts as its owner and the owner no longer has an active account in your organization. With HTTP Basic, the response has a WWW-Authenticate header.
429rate_limitedMore than 60 token requests came from your IP address in the current minute. Wait for the number of seconds in the Retry-After header.
500server_errorSomething went wrong on our end. Try again later.

Revoke a key

Open Admin console > Account > API keys  and revoke the key. Its tokens stop working right away. An admin can revoke any key of the organization, including keys that act as Conclude.

An expired key stops working the same way. The key list shows it as expired. Issue a new key before the old one expires, and revoke the old one.

When the key’s owner leaves

A key that acts as its owner depends on that person. Revoke a person’s keys when they leave your organization.

Conclude also revokes these keys in its nightly run, once the owner has no active account left in any of your workspaces. From that moment, the key and its tokens stop working.

In Microsoft Teams, Conclude sees an account as gone only when the user is deleted. Blocking sign-in in Entra ID is not enough.

A key that acts as Conclude belongs to the organization. It stays when the person who issued it leaves.