On this page

Authentication

All API requests are made on behalf of a registered User, using a bearer authentication token. We offer 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.web1on1.chat/v2/path/to/resource

Scopes, Permissions and Expiration

Time-based Tokens

Bearer tokens are time-based tokens that expire after 24 hours. After that, API requests will result in 403 Permission Denied responses, and a new access token should be requested using the refresh token.

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.web1on1.chat/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@web1on1.chat"
}

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.