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

# API Credentials

> Create a client ID and secret for your workspace and call the Talqui APIs with short-lived access tokens.

## Introduction

**API credentials** are the recommended way to connect your own systems (ERPs, BI tools, automation platforms, internal scripts) to a Talqui workspace. Each credential belongs to **one workspace** (tenant): it is not tied to a person, so it keeps working when the operator who created it leaves the team.

A credential is a **client ID** and a **client secret**. Your integration exchanges them for an **access token** that lasts **1 hour** and sends that token on every API request. This is the standard [OAuth 2.0 Client Credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) flow.

> [!NOTE]
>
> Credentials have full access to the data of their workspace. Treat the client secret like a password and keep it on your server, never in a browser or mobile app.

***

## Creating a credential

Only workspace **owners** and **managers** can manage credentials.

1. In the Talqui web app, open **Settings → API credentials** (*Credenciais de API*).
2. Click **New credential**, give it a name (for example, the system it connects) and, optionally, an expiration date.
3. Copy the **client ID** and the **client secret** right away. **The secret is shown only once**: if you lose it, rotate it to get a new one.

***

## Getting an access token

Send the client ID and secret with HTTP Basic authentication to the token endpoint:

```bash theme={null}
curl -X POST https://id-api.talqui.chat/api/auth/oauth2/token \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -d grant_type=client_credentials \
  -d scope=urn:talqui::::permission/all
```

The answer carries the token and its lifetime in seconds:

```json theme={null}
{
  "access_token": "tq_at_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "urn:talqui::::permission/all"
}
```

There is no refresh token: when the access token is about to expire, ask for a new one the same way. Reuse a token while it is valid instead of requesting one per API call.

***

## Calling the API

Send the access token as a Bearer token. Requests are scoped to the credential's workspace: use its tenant ID in the URL.

```bash theme={null}
curl https://services-api.talqui.chat/v1/tenants/<TENANT_ID>/contacts \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
```

A token used on another workspace is refused with `403`.

***

## What a credential can call

An API credential reaches the endpoints below. Any other endpoint answers `403`, including the ones that act as a person (operator presence, shortcuts, notifications), the workspace settings, analytics and plugins, and the legacy campaign endpoints of `https://api.talqui.chat`.

**Services API** (`https://services-api.talqui.chat`, every path starts with `/v1/tenants/{tenantID}`):

| Resource | Endpoints |
| - | - |
| Workspace | `GET /v1/tenants/{tenantID}` |
| Operators | `GET /operators` |
| Inboxes | `GET /inboxes` |
| Contacts | `GET /contacts`, `POST /contacts/by-ids`, `GET /contacts/tags`, `POST /contacts/segment`, `POST /contacts/segment/count`, `GET /contacts/lookup`, `GET /contacts/{contactID}`, `PATCH /contacts/{contactID}`, `PATCH /contacts/{contactID}/meta`, `GET /contacts/{contactID}/sessions` |
| Contact imports | `POST /contacts/imports`, `GET /contacts/imports`, `GET /contacts/imports/{importID}`, `GET /contacts/imports/{importID}/reports/{reportKind}` |
| Campaigns | `POST /campaigns`, `GET /campaigns`, `GET /campaigns/stats`, `GET /campaigns/{campaignID}`, `PATCH /campaigns/{campaignID}`, `DELETE /campaigns/{campaignID}`, `POST /campaigns/{campaignID}/schedule`, `POST /campaigns/{campaignID}/cancel`, `GET /campaigns/{campaignID}/progress` |
| Campaign models | `POST /campaigns-models`, `GET /campaigns-models`, `GET /campaigns-models/{campaignModelID}`, `PUT /campaigns-models/{campaignModelID}`, `DELETE /campaigns-models/{campaignModelID}` |
| Messages | `GET /messages`, `GET /messages/lookup`, `PUT /messages/{messageID}/transcribe` |
| Sessions | `GET /sessions/{sessionID}`, `GET /sessions/{sessionID}/messages`, `POST /sessions/{sessionID}/transcription`, `POST /sessions/{sessionID}/transcription/send` |

The request and response of each one are in the [Services API reference](https://docs.talqui.chat/api-reference/services-api/campaigns/create-campaign.md). Campaigns created by a credential are attributed to it. To send a campaign to one contact, see [Single Sends](https://docs.talqui.chat/guides/platform/campaigns/create-campaign-dispatch.md).

**REST API** (`https://api.talqui.chat`): only `POST /tenants/{tenantID}/sessions`, to [start a session](https://docs.talqui.chat/guides/platform/sessions/session-start).

***

## Managing credentials

In **Settings → API credentials** you can see who created each credential, its expiration and when it last issued a token, and:

* **Revoke** it: new tokens are refused at once and tokens already issued stop working within a few minutes. Use this if a secret leaks.
* **Reactivate** a revoked credential.
* **Rotate the secret**: the old secret stops working at once; tokens already issued stay valid until they expire (up to 1 hour).
* **Delete** a revoked credential.

An expired credential stops issuing tokens. Create a new one to replace it.

***

## Other authentication methods

Plugins keep authenticating with their own credentials (`Plugin` and `PluginConnection`), described in [Authentication](https://docs.talqui.chat/guides/introduction/authentication). Integrations already using a plugin connection credential keep working; API credentials are the path for new integrations.


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