Skip to main content
An API credential is for a system, not a person: your CRM, your own chatbot, an internal app. It gets its own token with OAuth 2.0 client_credentials, so the integration keeps working when someone leaves the company or changes their password, and it can only do what the credential allows. If a person is calling the API, sign in instead.

What a credential can do

You choose the access when you create it. Today there are two: Everything else answers 403, even with a valid token. A credential cannot create knowledge bases, write content, or reach the Cloud Chat API.

Create a credential

An account administrator creates it in Cloud Chat, under Settings → API and integrations → API credentials → New credential. The flow asks for a name, the access, and the projects when the access includes the Playground. At the end it shows two values:
  • client_id, which you can see again on the credential at any time.
  • client_secret, which is shown only once. Copy it into your system’s secret store right away. If it is lost, create a new credential; there is no way to show it again.

Get a token

Exchange the two values for an access token:
Sending client_id and client_secret in the form body instead of the Authorization header also works. The token carries every access the credential has, so there is no scope to send.
Use the access_token here. That is the opposite of a user sign-in, where the API wants the id_token: a credential token carries no identity of a person, only the credential’s access.

Call the API

Send the token as a bearer token. A Playground call looks like this:
A project the credential does not cover answers 404, the same as a project that does not exist.

Reuse the token until it expires

expires_in says how many seconds the token is valid. Keep the token and reuse it on every call until it is close to that limit, then request a new one with the same client_id and client_secret. There is no refresh token in this flow: the secret is what renews access, and it does not expire. Do not request a token per call. Token requests have their own rate limit, lower than the API’s, and a system that asks for one on every request hits it quickly.
If a call answers 401 before the expiry you expected, request a new token once and retry.

Rate limits

Token requests are limited per credential and per IP, and API calls per credential. When a limit is reached the response is 429 with a Retry-After header, in seconds. Responses also carry RateLimit-Remaining and RateLimit-Reset, so your system can slow down before it gets there. Read those headers rather than hardcoding a number: the limits can change.

Change the secret or stop a credential

A secret cannot be changed in place. To replace it:
  1. Create a new credential with the same access.
  2. Put its client_id and client_secret in your system.
  3. Once the system is using the new one, deactivate the old credential.
Deactivating stops new tokens right away. Tokens already issued keep working until they expire, so allow up to expires_in seconds for a deactivation to take full effect. A deactivated credential cannot be reactivated. An account has a limit of active credentials. When it is reached, Cloud Chat says so and you deactivate one before creating another.

Errors