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" \
       https://api.chatshipper.com/v2/path/to/resource

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.

Scopes

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

Permissions

Permission Guest Agent Bot Admin
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 https://api.chatshipper.com/v2/auth/token. 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": "admin@example.org",
  "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 has expired, we can create new access tokens by using the refresh token in a GET request, with the access token as the Bearer token in the Authorization header.

Request: GET /v2/auth/token?refreshToken=599e1fcd9da1c72645c95886.28167e54e423275c0d948

After an access token has already expired, we need to POST to the endpoint without an Authorization header (use as a public endpoint). In this scenario, the payload consists of the refreshToken and a clientId being the user or bot email.

Request: POST /v2/auth/token

{
  "refreshToken": "599e1fcd9da1c72645c95886.28167e54e423275c0d948ce2efca",
  "clientId": "bot+5f47d86c51755a001dc41b82@chatshipper.com"
}

In both cases, 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](https://api.chatshipper.com/).