API Credentials - Talqui Developer Hub

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 flow.

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.

In the Talqui web app, open Settings → API credentials (Credenciais de API).
Click New credential, give it a name (for example, the system it connects) and, optionally, an expiration date.
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:

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:

{
  "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.

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. Campaigns created by a credential are attributed to it. To send a campaign to one contact, see Single Sends. REST API (https://api.talqui.chat): only POST /tenants/{tenantID}/sessions, to start a session.

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. Integrations already using a plugin connection credential keep working; API credentials are the path for new integrations.

​Introduction

​Creating a credential

​Getting an access token

​Calling the API

​What a credential can call

​Managing credentials

​Other authentication methods

Introduction

Creating a credential

Getting an access token

Calling the API

What a credential can call

Managing credentials

Other authentication methods