Authentication
To use the Qiscus Omnichannel API, you must authenticate yourself. Only users with valid authentication tokens can access the service.
Login
You must authenticate yourself using basic authentication (email, password) when you log in. The following are the login API you can use:
Base URL:
[POST] https://omnichannel.qiscus.com/api/v1/authSample Request Body:
{ "email": "{{AdminEmail}}", "password": "{{AdminPassword}}",}CURL Sample:
curl --location 'https://omnichannel.qiscus.com/api/v1/auth' \--form 'email="techxxxxx@gmail.com"' \--form 'password="xxxxx"'Sample Response:
{ "data": { "user": { "id": 1***1, "name": "Tech Wrt Corp.", "email": "xxxtechwrt.xxx@gmail.com", "authentication_token": "QEX247AIhJVuDi0WxxNrOhWzAxxxxx", "created_at": "2024-07-15 04:33:47", "updated_at": "2024-12-18 06:21:55", "sdk_email": "xxxxx_admin@qismo.com", "sdk_key": "****", "is_available": true, "type": 1, "avatar_url": "https://xxxxx.cloudfront.net/xxxxxx/image/upload/xxxxx/image.png", "app_id": 1xxxx4, "is_verified": true, "notifications_room_id": null, "bubble_color": null, "qismo_key": "****", "direct_login_token": "****", "last_login": "2024-12-18 06:18:16", "force_offline": false, "deleted_at": null, "is_toc_agree": true, "totp_token": "****", "is_req_otp_reset": null, "last_password_update": "2024-12-17 06:59:59", "type_as_string": "admin", "assigned_rules": null, "app": { "app_code": "xxxxx", "secret_key": "****", "name": "Tech Wrt Crop.", "bot_webhook_url": null, "is_bot_enabled": false, "is_allocate_agent_webhook_enabled": false, "allocate_agent_webhook_url": null, "mark_as_resolved_webhook_url": null, "is_mark_as_resolved_webhook_enabled": false, "is_active": true, "is_sessional": true, "is_agent_allocation_enabled": false, "is_agent_takeover_enabled": true, "use_latest": false, "is_bulk_assignment_enabled": false } }, "details": { "is_integrated": true, "sdk_user": { "id": 2xxxxx5, "token": "d4WyAto3IFKz2nCi1xxxxx", "email": "xxxxx_admin@qismo.com", "display_name": "Tech Wrt Corp.", "avatar_url": "https://xxx.cloudfront.net/xxx-prod/image/upload/xxx/image.png", "extras": { "type": "agent", "user_bubble_color": null } }, "app": { "app_code": "xxxxx", "secret_key": "****", "name": "Tech Wrt Crop.", "bot_webhook_url": null, "is_bot_enabled": false, "is_allocate_agent_webhook_enabled": false, "allocate_agent_webhook_url": null, "mark_as_resolved_webhook_url": null, "is_mark_as_resolved_webhook_enabled": false, "is_active": true, "is_sessional": true, "is_agent_allocation_enabled": false, "is_agent_takeover_enabled": true, "use_latest": false, "is_bulk_assignment_enabled": false } }, "long_lived_token": "hoVjTxxxxx", "user_configs": { "notifagentjoining": null, "is_notifagentjoining_enabled": true, "notifmessagecoming": null, "is_notifmessagecoming_enabled": false }, "use_2fa": false, "need_setup_otp": false }}| Field | Type | Description |
|---|---|---|
| data.user.authentication_token | string | This field is equal to Short lived token. Token will expired in 30 days and every login usage will produce new token that doesnt make the old valid token expired |
| data.long__lived__token | string | This token will be used in token management api, such as : refresh_token, revoke_ token, active_token_list |
Authentication Type
There are two types of authentication used by Qiscus Omnichannel Chat, REST Token and Short lived Token.
REST Token
The REST Token is used to authenticate server to server using the app code and secret key. Here is the REST token implementation:
- How to get app id and secret
- Usage Sample:
#example: calling list of channels apicurl --location --request GET 'https://omnichannel.qiscus.com/api/v2/channels' \--header 'Qiscus-App-Id: YOUR_APP_ID' \--header 'Qiscus-Secret-Key: YOUR_SECRET_KEY'You can always call any API using this method without worrying about token expiration.
Short Lived Token
To keep your information safe, you can choose to use a short lived token for authentication. Starting 4th November 2020, Qiscus Omnichannel Chat will enforce a provision whereby the short lived token validity period is 30 days after the token was generated. However, the validity period of short lived token will change under certain circumstances:
- When a user log in to Qiscus Omnichannel Chat, a short lived token will be generated and by default will expire in 30 days.
- If a user log out before the expiration date, the short lived token will become invalid. Hence, user must log back in.
- Once user log back in, a new short lived token will be generated. The new token will expire in the next 30 days from the last log in date.
You can see the image below to understand short lived token period clearly.
The following is a list of APIs that will be impacted if you implement a short live token:
1. Refresh Token
If the short lived token is expired. You can use the following API.
Base URL:
[POST] https://omnichannel.qiscus.com/api/v2/auth/refresh_tokenHeaders:
Qiscus-App-Id : YOUR_APP_IDAuthorization : YOUR_LONG_LIVED_TOKENSample Response:
{ "data": { "auth": { "expired_at": "2025-01-23T02:59:14Z", "token": "QEX1Lx1mXIzxxxxx" } }, "status": 200}When to refresh your token?
If you got response error.detail = ‘token_expired’ like below payload when calling any API, you should revoke your token
http_status: 401Response:{ "errors": "SOME_ERROR_MESSAGE" "status": 401 "detail": "token_expired"}2. Revoke Token
Revoke token you want to be revoked.
Base URL:
[POST] https://omnichannel.qiscus.com/api/v2/auth/revoke_tokenHeaders:
Qiscus-App-Id : YOUR_APP_IDAuthorization : YOUR_LONG_LIVED_TOKENBody:
{ "token": "YOUR_TOKEN_YOU_WANT_TO_BE_REVOKED"}Sample Response:
{ "data": { "status": "ok" }}3. Revoke All Token
This token will revoke all your active token and give you a new one.
Base URL:
[POST] https://omnichannel.qiscus.com/api/v2/auth/revoke_all_tokenHeaders:
Qiscus-App-Id : YOUR_APP_IDAuthorization : YOUR_LONG_LIVED_TOKENSample Response:
{ "data": { "auth": { "expired_at": "2024-12-24T11:25:47Z", "token": "QEXxt71Joyxxxxx" } }, "status": 200}4. List of Active Sessions
See all of your active sessions.
Base URL:
[GET] https://omnichannel.qiscus.com/api/v2/auth/active_sessionsHeaders:
Qiscus-App-Id : YOUR_APP_IDAuthorization : YOUR_LONG_LIVED_TOKENSample Response:
{ "data": { "auth": [ { "expired_at": "2024-12-24T11:25:47Z", "token": "QEXxt71Joyxxxxx" } ] }, "meta": { "limit": 20, "page": 1, "total": 1, "total_page": 1 }, "status": 200}