> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudhumans.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API credentials

> Let one of your systems call the Claudia API on its own, without anyone's login.

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](https://docs.cloudhumans.com/api-reference/claudia/sign-in.md) instead.

## What a credential can do

You choose the access when you create it. Today there are two:

| Access | What the system can do | Applies to |
| - | - | - |
| **Knowledge bases**, read | [List knowledge bases](https://docs.cloudhumans.com/api-reference/claudia/v1/knowledge-bases/list-knowledge-bases.md), get one, [list and search content](https://docs.cloudhumans.com/api-reference/claudia/v1/knowledge-base-content/list-and-search-content.md), read an entry, list the tags and topics in use | Every knowledge base of the account |
| **Playground**, invoke | [Send a message to ClaudIA and read its answer](https://docs.cloudhumans.com/api-reference/claudia/v1/playground/send-a-message-to-claudia-and-read-its-answer.md) | Only the projects you select |

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:

```bash theme={null}
curl -X POST https://api.cloudhumans.com/auth/v1/token \
  -u "<YOUR_CLIENT_ID>:<YOUR_CLIENT_SECRET>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"
```

```json theme={null}
{
  "access_token": "eyJraWQiOi...",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

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.

> [!WARNING]
>
> 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:

```bash theme={null}
curl -X POST https://api.cloudhumans.com/claudia/v1/playground/invoke \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project": "<YOUR_PROJECT>", "message": "my order 12345 has not arrived yet"}'
```

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.

```python theme={null}
import time
import requests

TOKEN_URL = "https://api.cloudhumans.com/auth/v1/token"
_cache = {"token": None, "expires_at": 0}

def access_token(client_id, client_secret):
    if _cache["token"] and time.time() < _cache["expires_at"] - 60:
        return _cache["token"]
    response = requests.post(
        TOKEN_URL,
        auth=(client_id, client_secret),
        data={"grant_type": "client_credentials"},
        timeout=10,
    )
    response.raise_for_status()
    body = response.json()
    _cache["token"] = body["access_token"]
    _cache["expires_at"] = time.time() + body["expires_in"]
    return _cache["token"]
```

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

| Response | What it means |
| - | - |
| `400` `unsupported_grant_type` on `/auth/v1/token` | The body is missing `grant_type=client_credentials`. |
| `400` or `401` `invalid_client` on `/auth/v1/token` | Wrong `client_id` or `client_secret`, or the credential was deactivated. |
| `401` `invalid or expired token` | The token expired or is malformed. Request a new one. |
| `403` `Forbidden` | The token is valid but the credential does not have this access. |
| `404` on a project or knowledge base | It is not covered by the credential, or it does not exist. The two answer the same on purpose. |
| `429` | A rate limit was reached. Wait for `Retry-After` and try again. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.