Find your credentials

Every Cloud Chat API call needs three things: a token, your cloudchat-instance header, and one of your account ids. This page gets you all three, and ends with a request you can run as-is. Some accounts do not get a token on the first try — a temporary password or two-step verification comes back as a challenge instead. The form handles that: the second step appears only when there is one, already carrying what the first step returned, so the only thing left to type is the code from the text message. Writing this into your own client means writing a loop, not a single call. Signing in is a loop, not a call on the overview page has the state machine and the three things worth knowing before a real user meets it.

Find your instance and account

Paste the id_token from above. The values are remembered, so they show up on every endpoint page from here on.

Your password and your token go to api.cloudhumans.com, and nowhere else. Each is sent there over HTTPS — the password once, to get you a token; the token once, to look up your account names. This page makes no other request with either, stores neither, and logs nothing. You can confirm that in your browser’s network tab.That is also why the token is pasted rather than carried over for you: nothing here is kept, so there is no credential of yours sitting at rest in your browser.api.cloudhumans.com is also the only place your token should ever go. Any other site offering to “check” or “decode” it for you is not one to trust.

If the values are missing or don’t work

Symptom	What it means
Account names never appear, only ids	The name lookup is unavailable from your browser. Harmless — the ids shown are correct and every call works with them.
The box says the token carries no accounts	You pasted the `access_token` instead of the `id_token`, or your user has no Cloud Chat access yet.
An account you expect is missing	If the access was granted after you signed in, your token predates it. Sign in again for a fresh one.
An account you no longer have still appears	Same cause in reverse: your token predates the change. It disappears once the name lookup answers, or after you sign in again.
`400` with `cloudchat-instance header is required`	The header never arrived. It is rejected before authentication, so this is not a token problem.
`401` on every call	Expired or malformed token. Sign in again; `expires_in` in the sign-in response says how long the new one lasts.
`404` with a correct-looking token	Right token, wrong pairing — and this is the common one. Either the account id isn’t on the instance you sent, or your user has no access to it. Those two answer identically on purpose, so re-check both values above.
`403` with a correct-looking token	Different problem: you do have access and the account is suspended. Nothing will work on it until that’s resolved.
An account the box won’t generate a call for	The token names an internal instance, which this API does not serve.

Getting these values without this page

Both of the box’s sources are things you can call yourself.Ask the API — this one includes account names:

curl https://api.cloudhumans.com/auth/v1/me/cloudchat-accounts \
  -H "Authorization: Bearer $ID_TOKEN"

[{ "instance": "1", "accountId": 1, "accountName": "Cloudhumans" }]

Read the token — ids only, and no network call. A JWT payload is base64url JSON, so the claim is one command away:

echo "$ID_TOKEN" | cut -d. -f2 \
  | tr '_-' '/+' \
  | base64 -d 2>/dev/null \
  | jq -r '."custom:cloudchat_accounts"'

import base64, json, os

payload = os.environ["ID_TOKEN"].split(".")[1]
payload += "=" * (-len(payload) % 4)
claims = json.loads(base64.urlsafe_b64decode(payload))
print(claims["custom:cloudchat_accounts"])

You get something like 1:1:1,1:2:0, read as instance:account:role. The role is a number — 0 agent, 1 administrator, 2 supervisor, 3 assistant, 4 cx_engineer — and it has no effect on the values you send; it is your permission level inside the account, which Cloud Chat enforces on its own.The endpoint is the authority; the claim is an offline approximation of it. Cloud Chat authorizes on your live access, which is what the endpoint reads. The claim is a photograph taken when you signed in, so it can still list an account whose access was revoked since, or miss one granted since. That is why the box shows the endpoint’s answer whenever it gets one, rather than merging the two — a merged list would offer you accounts your calls would only 404 on.Use the claim when you want an answer with no network call, and re-read it after signing in again.If you have devtools open you may see the name lookup fail with a CORS error while that endpoint is still rolling out. Nothing is broken — it is why the box falls back to reading your token, and the ids it shows are the ones the API accepts.

Getting Started

Authentication

Canned Responses

Conversations

Labels

Inboxes

Agents

Teams

Macros

Automation Rules

Availability Reasons

Help Center

Uploads

Find your credentials

Find your instance and account

If the values are missing or don’t work

​Sign in

​Find your instance and account

​If the values are missing or don’t work

Sign in

Find your instance and account

If the values are missing or don’t work