Skip to main content
To interact with Text APIs, your requests need to be authenticated. Text uses OAuth 2.1 for both:
  • Authentication confirms who you are — like checking your passport at security.
  • Authorization determines what you’re allowed to do — like being permitted into first class.
For API calls, both happen through a single token sent with each request. In most cases, the easiest way to authenticate is with a personal access token (PAT) — it lets your script or service call the APIs directly, without implementing a full authorization flow. If you’re building a solution that needs to act on behalf of multiple users, use OAuth authorization flows instead. Every request carries a token — a credential that tells the API who’s calling and what they’re allowed to do. Text has two separate token types, one per side of a conversation. They’re not interchangeable: an agent token won’t work on the Customer Chat API, and a customer token won’t work anywhere else.

​
Agent authorization

Agent tokens are used for the Agent Chat API, Configuration API, Reports API, and most other Text APIs — automations, bots, reporting tools, anything acting on the agent side. There are three ways to get an agent token, each suited to a different situation.

Personal access token

A permanent token tied to your account. The fastest path to a working API request — good for personal scripts, internal tools, and testing.

OAuth access token

A short-lived token obtained through the OAuth flow. Use this when your app acts on behalf of other users — each user authorizes your app independently with their own credentials.

Bot token

A token issued to a bot agent. Bots are created via the Configuration API and interact with the Agent Chat API just like any other agent.
If you’re just getting started, a personal access token is the quickest option. Requests use Authorization: Basic <token> — Text gives you the ready-to-paste value. If your integration needs to access the API on behalf of multiple agents, use OAuth authorization flows instead. OAuth allows each user to authorize your integration with their own account, and requests are executed using their identity and permissions.
OAuth tokens use Bearer auth: Authorization: Bearer <access_token>. They expire after 8 hours (28,800 seconds) — use the refresh token to get a new one without asking the user to re-authorize.There’s a limit of 25 active access tokens and 25 refresh tokens per client per user. When you exceed either limit, the oldest is automatically revoked.To revoke an OAuth access token before it expires, call DELETE https://accounts.livechat.com/v2/token. Revoking an access token also revokes its paired refresh token. To inspect any token and confirm it’s still valid, call GET https://accounts.livechat.com/v2/info.

​
Customer authorization

Customer tokens are used exclusively with the Customer Chat API; if you’re building a custom chat interface for customers on your website, in your app, or on another channel, this is the token type you need. The Customer Chat API uses a different authorization model than agent-side APIs. To learn how to authenticate customer-related requests, see customer authorization.

​
Scopes

Every token carries a set of scopes — a fixed list of what it’s permitted to do. Scopes are set at creation time and can’t be changed afterward. A token with chats--all:ro can read all chats but not send messages. A token with chats--all:rw can do both. Calling a method your token doesn’t have a scope for returns an error. Each method in the API reference lists exactly which scope it requires.
Start with the minimum scopes you need. You can always create a new token with broader permissions later.
Scope names are built from two parts: a resource segment and an access level. The access levels are ro (read only), rw (read and write, which implies ro), and rc (read and create). The resource segment is either all (all users’ resources) or my (the token owner’s only) — all implies my. So chats--all:rw grants read and write access to every chat on the license.

​
Global Accounts

If you decide to implement an authorization flow instead of using a PAT, make sure you understand the concept of Global Accounts.