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: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.
Call the API
Send the token as a bearer token. A Playground call looks like this: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.
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 is429 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:- Create a new credential with the same access.
- Put its
client_idandclient_secretin your system. - Once the system is using the new one, deactivate the old credential.
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.