OAuth authorization

OAuth authorization lets your application access Text APIs on behalf of a user, instead of as one fixed account like a personal access token does. Each user authorizes your application with their own account. Your app then receives an access_token that can be used to call the APIs using that user’s identity and permissions. OAuth is typically used when building applications that other users sign in to — for example, integrations or services that need to access data from multiple accounts. Text supports the following OAuth flows:

These flows return an access token for calling agent-side APIs — like the Agent Chat API or the Configuration API — on behalf of an agent. To authorize calls to the Customer Chat API, use customer authorization.

OAuth clients

Before you can use any OAuth flow, create an OAuth client in Text at Settings → API access → OAuth clients. Every client you create there belongs to your organization: it can only authorize accounts that belong to the same organization that created it. When you create a client, you choose a client type:

Web app — for apps that run in a browser and can’t store a secret. In OAuth terms, this is a public client.
Server-side app — for apps that run on a server and can store a Client Secret. In OAuth terms, this is a confidential client.

“Public client” is standard OAuth terminology for an app that can’t protect a secret — it says nothing about who can use the app. Every OAuth client you create in Text stays private to your organization regardless of its type.

The client type determines how you authenticate at the token endpoint and how refresh tokens behave:

Client type	Client Secret required	Refresh token behavior
Web app	no	rotates; each one is single-use
Server-side app	yes	does not rotate

Which OAuth flow to choose

If you’re building	Use this flow
a browser-based app (Web app client)	Authorization code grant with PKCE
a server-side app that can securely store a Client Secret	Authorization code grant
an internal tool your own team signs in to	Sign in with Text

Authorization code grant

The recommended flow for both client types, and the only recommended flow for browser-based apps (with PKCE). It returns a short-lived code that your app exchanges for an access_token and a refresh_token, so the token itself never appears in a redirect URL.Example: an integration where every agent in your organization connects their own CRM account and syncs chat data under their own permissions.

A ready-made login button instead of implementing the redirect flow yourself — it’s not a separate grant, it’s the Accounts SDK wrapping the authorization code or implicit grant for you. Because an OAuth client can only authorize accounts in the organization that created it, this fits an internal tool built for your own team, not a public login button.Example: an internal dashboard or browser extension where your agents sign in with their existing Text account instead of separate credentials.

Implicit grant

Returns the access_token directly in the redirect URL fragment and doesn’t issue a refresh token. The OAuth spec has moved toward the authorization code grant with PKCE for browser apps, though Text still fully supports the implicit grant for apps that already depend on it.Example: choose it if you’re maintaining an existing browser app that already relies on getting a token directly in the redirect URL.

Managing tokens

The following endpoints work with access and refresh tokens from any of the flows on this page.

Revoking tokens

Revoke a token — for example, when a user disconnects your app — with an HTTP DELETE request. Revoking either an access token or its corresponding refresh token revokes both:

https://accounts.livechat.com/v2/token

Parameter	Required	Description
`code`	yes, unless sent via the `Authorization` header	The `access_token` or `refresh_token` to revoke.

curl "https://accounts.livechat.com/v2/token" \
  -H "Authorization: Bearer <access_token_or_refresh_token>" \
  -X DELETE

curl "https://accounts.livechat.com/v2/token?code=test_YTJQ6GDVgQf8kQDPw" \
  -X DELETE

A successful request returns 200 OK with an empty body.

Validating the access token

Make an HTTP GET request to check whether an access token is valid:

https://accounts.livechat.com/v2/info

Validate an access token

curl "https://accounts.livechat.com/v2/info" \
  -H "Authorization: Bearer <access_token>"

Response

{
  "access_token": "test_YTJQ6GDVgQf8kQDPw",
  "account_id": "bbe8b147-d60e-46ac-a1e5-1e94b11ea6e1",
  "client_id": "9cbf3a968289727cb3cdfe83ab1d9836",
  "expires_in": 28725,
  "organization_id": "390e44e6-f1e6-0368c-z6ddb-74g14508c2ex",
  "scope": "chats--all:ro,chats--all:rw",
  "token_type": "Bearer"
}

Refresh tokens can’t be validated directly with this endpoint.

Limits

Each OAuth client can issue up to 20 active access tokens without a refresh token per user account — for example, tokens from the implicit grant. Issuing another token revokes the oldest one.
Each OAuth client can issue up to 20 active access-and-refresh-token pairs per user account — for example, pairs from the authorization code grant. Issuing another pair revokes the oldest one.
Text allows up to 30 authorization redirects in 30 seconds per client per user account. Requests beyond that limit redirect to an error page with too_many_redirects details.

Redirect URIs

You can configure multiple comma-separated redirect URIs for an OAuth client. When you configure a redirect URI, it must meet these requirements:

Server-side app clients must use an http or https scheme.
Web app clients can also use a custom scheme, like myapp://callback — Text then requires PKCE on the authorization request.
It has no query string.
It has no fragment.
It has no path traversal segments (..).

When Text validates the redirect_uri in an authorization request against your configured URIs, it requires an exact match on scheme and host. The path either has to match exactly or has to be a subpath of a configured path, split on / boundaries — so a configured path never matches as a prefix of a different, longer path segment.

Configured redirect URI	`redirect_uri` in the request	Valid	Why
`http://example.com`	`http://example.com`	yes	exact match
`http://example.com/callback`	`http://example.com/callback`	yes	exact match
`http://example.com/callback`	`http://example.com/callback/success`	yes	subpath of the configured path
`http://example.com/callback`	`http://example.com/callbackx`	no	not a subpath — no `/` boundary after `callback`
`http://example.com/callback`	`http://example.com/`	no	request path does not contain the configured path
`http://localhost:3000`	`http://localhost:4000`	no	host mismatch
`https://example.com`	`http://example.com`	no	scheme mismatch

To avoid ambiguity, configure and use an exact redirect URI whenever your app’s flow allows it.

Getting started

Key concepts

API overview

Authentication

OAuth clients

Which OAuth flow to choose

Managing tokens

Revoking tokens

Validating the access token

Limits

Redirect URIs

​OAuth clients

​Which OAuth flow to choose

​Managing tokens

​Revoking tokens

​Validating the access token

​Limits

​Redirect URIs

OAuth clients

Which OAuth flow to choose

Managing tokens

Revoking tokens

Validating the access token

Limits

Redirect URIs