The ChatShipper Developer Hub

Welcome to the ChatShipper developer hub. You'll find comprehensive guides and documentation to help you start working with ChatShipper as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

2. Authentication

All API requests are made on behalf of a registered User, using a bearer authentication token. We offer both permanent api keys and time-based tokens. An API request should always include the Authorization: Bearer _token_ header in the request HTTP headers list.

Example of valid API requests using the cURL utility:

$ curl -H "Authorization: Bearer 94c70d470e391bdc16a8d8363b5d4891" \

Scopes, Permissions and Expiration

ChatShipper provides two types of access tokens:

  1. Permanent Bot API tokens for server-to-server communication (backend automations, bots);
  2. Time-based, expiring Tokens for browser-to-server communication (user logins) and for requests that need admin permissions/scope.

Non-expiring "bot user" Tokens

For server-to-server communication, a non-expiring (yet revokable) token should be used. These tokens are a property of any bot user in the system.

These API tokens do not expire, but may be revoked simply by deleting the bot user. The API token has the permissions of the associated user, and actions appear as if they were that user. If the associated user has its permissions changed, such as being removed from an organization, then the functionality of the token will change.

Time-based Tokens

ChatShipper supports time-based tokens that expire after a set amount of time. These tokens are tied to the user session, and used primarily for browser-to-server communications like our frontend applications.

Time-based access tokens are invalidated after 24 hours. After that, API requests will result in 403 Permission Denied responses, and a new access token should be requested.


Token permissions are described as a space-delimited OAuth 2.0 Access Token Scope string inside the JWT token.

The following scopes, in ascending order of permissions, are available:

  • guest
  • agent
  • bot
  • admin

API Key tokens must have one or more scopes specified as an array of strings when the token is created. Time-based tokens have the scope correspond to the role of the User.

Scopes are meant to be cascading: for example, a bot scoped key is expected to include the lower-level scopes (agent and guest).


List organizations--++
List organization groups--++
List users--++
List conversations-+++
List messages--++
List contacts-+++
List knowledge items-+++
List forms--++
List services---+
Fetch organization--++
Fetch organizationGroup--++
Fetch user details (self)++++
Fetch user details--++
Fetch conversations details++++
Fetch message--++
Fetch contact--++
Fetch knowledge item-+++
Fetch form---+
Fetch service---+
Create organization---+
Create organizationGroup---+
Create user---+
Create conversation-+++
Create message++++
Create contact--++
Create knowledge item-+++
Create form--++
Create service---+
Update organization---+
Update organizationGroups---+
Update user details (self)++++
Update user details---+
Update conversation---+
Update message--++
Update contact--++
Update knowledge item-+++
Update form--++
Update service---+
Delete knowledge item--++
Delete other resource---+

Requesting and Refreshing API Tokens

Create an access token

To obtain an access token, make a POST request to
The users's email and password must be used in a JSON object posted to the token API URL.

Request: POST /v2/auth/token

  "email": "[email protected]",
  "password": "t0pZ3kR3t"

Response: 200 OK

    "tokenType": "Bearer",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI1OTllMWZjZDlkYTFjNzI2NDVjOTU4ODYiLCJzY29wZSI6ImFkbWluIiwiaWF0IjoxNTAzNjIwNjI0LCJleHAiOjE1MDQ4MzAyMjR9.Hqvi97eSODiQkcVvYxX_Gi5sN87l7Pj5toGlebghsPM",
    "refreshToken": "599e1fcd9da1c72645c95886.28167e54e423275c0d948ce2efcaa481d4ab229ea53800502c26adae924a217f924fe2ba343d78ac",
    "user": "599e1fcd9da1c72645c95886",
    "scope": "admin"

As we can see, an access token and a refresh token are created. We can make protected api calls with the accessToken.

The token expires after 24 hours, at which point a new token should be generated. It's best, however, to request a new access token before it expires - by using the refresh token.

Refresh an access token

Before an access token is no longer valid, we need to create a new one by using the refresh token.

GET /v2/auth/token?refreshToken=599e1fcd9da1c72645c95886.28167e54e423275c0d948ce2efcaa481d4ab229ea53800502c26adae924a217f924fe2ba343d78ac

The result will be the same as the token creation response; the new access token and refresh token should be used in future API calls.

For more information, review the full API Reference.

Updated 6 months ago

2. Authentication

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.