Authentication

AI Tools

To use the Qiscus Omnichannel API, you must authenticate yourself. Only users with valid authentication tokens can access the service.

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/auth

Sample Request Body:

{ "email": "{{AdminEmail}}", "password": "{{AdminPassword}}", }

CURL Sample:

curl --location 'https://omnichannel.qiscus.com/api/v1/auth' \ --form 'email="[email protected]"' \ --form 'password="xxxxx"'

Sample Response:

{ "data": { "user": { "id": 1***1, "name": "Tech Wrt Corp.", "email": "[email protected]", "authentication_token": "QEX247AIhJVuDi0WxxNrOhWzAxxxxx", "created_at": "2024-07-15 04:33:47", "updated_at": "2024-12-18 06:21:55", "sdk_email": "[email protected]", "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": "[email protected]", "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 api curl --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_token

Headers:

Qiscus-App-Id : YOUR_APP_ID Authorization : YOUR_LONG_LIVED_TOKEN

Sample 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: 401 Response: { "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_token

Headers:

Qiscus-App-Id : YOUR_APP_ID Authorization : YOUR_LONG_LIVED_TOKEN

Body:

{ "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_token

Headers:

Qiscus-App-Id : YOUR_APP_ID Authorization : YOUR_LONG_LIVED_TOKEN

Sample 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_sessions

Headers:

Qiscus-App-Id : YOUR_APP_ID Authorization : YOUR_LONG_LIVED_TOKEN

Sample Response:

{ "data": { "auth": [ { "expired_at": "2024-12-24T11:25:47Z", "token": "QEXxt71Joyxxxxx" } ] }, "meta": { "limit": 20, "page": 1, "total": 1, "total_page": 1 }, "status": 200 }

Last updated on Apr 9, 2025

Was this page helpful?

Authentication

Login

Authentication Type

REST Token

Short Lived Token