Keys and tokens Beta

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.

1. Open Admin console > Users and access > 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 active keys.

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 public channels and the private channels that Conclude was added to. 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. 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 connections, the token needs a subject.
• Without a subject, the token can read connections and the audit log. 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.

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.

GET /v1/apiKey works with any scope.

The dialog also offers these scopes: users:read, users:readwrite, activities:read, activities:readwrite, chats:read, chats: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, but not both.

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"
}

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"}

Revoke a key

Open Admin console > Users and access > 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.

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, Conclude refuses new tokens for the key. Tokens issued before then work until they expire, at most one hour later.

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.