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:

Sample Request Body:

CURL Sample:

Sample Response:

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:

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:

1. When a user log in to Qiscus Omnichannel Chat, a short lived token will be generated and by default will expire in 30 days.

2. If a user log out before the expiration date, the short lived token will become invalid. Hence, user must log back in.

3. 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:

Headers:

Sample Response:

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

2. Revoke Token

Revoke token you want to be revoked.

Base URL:

Headers:

Body:

Sample Response:

3. Revoke All Token

This token will revoke all your active token and give you a new one.

Base URL:

Headers:

Sample Response:

4. List of Active Sessions

See all of your active sessions.

Base URL:

Headers:

Sample Response:

Single Sign-On (SSO)

Single Sign-On (SSO) lets your team access Qiscus Omnichannel through your organization's existing identity provider, instead of maintaining separate Qiscus credentials.

For growing teams, SSO keeps access management centralized: your team signs in with the identity they already use, and you decide who can access Qiscus from a single place — your identity provider. Disable or remove someone there, and they can no longer sign in to Qiscus. SSO handles sign-in (authentication) only; creating and removing Qiscus accounts is still done in Qiscus, with automated provisioning and de-provisioning (SCIM) planned for a future release.

The result is enterprise-grade access control for your admins, and a familiar, password-free sign-in experience for your team.

How SSO Works

SSO follows the standard SAML 2.0 handshake. Understanding the flow helps you know what to expect at each stage:

1. A user starts login. On the Qiscus login page, the user selects "Login with SSO" and enters their workspace address.

2. Redirect to your IdP. Qiscus redirects the user to your identity provider's login page.

3. Your IdP authenticates the user. The user signs in with their corporate credentials, including any multi-factor authentication (MFA) your IdP enforces.

4. Return to Qiscus. Your IdP sends a signed SAML assertion back to Qiscus. Qiscus validates the signature, matches the user by email, and establishes a session.

5. Land on the dashboard. The user is taken straight into the Omnichannel dashboard, already signed in.

Before You Start

Make sure you have these ready:

• Admin access to Qiscus — You'll need an administrator account to reach the setup page.

• Access to your company's login system — The admin area of your login provider (like Okta, Microsoft, or Google), where you'll add Qiscus as a connected app.

• Your login system's settings file — A small file (called SAML metadata) from your provider. You can bring it as a web link or as a downloaded file (up to 5 MB).

• Your team already added in Qiscus — Everyone who will log in must already exist in Qiscus, using the same email they use in your login system.

Setting Up SSO

Setting up Single Sign-On (SSO) is a one-time configuration. Follow the steps below to set up SSO.

1. Navigate to Settings, select Single Sign-On

2. Complete the guided setup wizard. Each step is validated before you can proceed, ensuring your configuration is correct.

3. Enter a Workspace Address and click Next button

4. Copy Qiscus's details, its ACS URL and Entity ID into your login provider so the two can recognize each other.

5. Enter the metadata URL or upload the metadata file (maximum 5 MB). Qiscus automatically populates the required configuration. Copy the Connection Details from Qiscus and add them to your Identity Provider configuration.

6. Configure the Email Attribute. Specify the email attribute from your Identity Provider and click Next

7. Test and Enable SSO. Run the configuration test. If it succeeds, click Finish Setup to enable Single Sign-On.

8. Single Sign-On is now active and ready to use.

From the SSO header, you can manage your connection anytime:

• Toggle — Turn SSO on or off without deleting your setup.

• Test Connection — Check that everything is still working.

• Edit — Update your login system or settings.

• Disconnect — Remove SSO completely and start fresh.

Signing In With SSO (For Team Members)

Once SSO is active, signing in takes just a few steps:

1. On the Qiscus login page, choose Login with SSO.

2. Enter your organization's workspace address. Our system will record the last workspace used on your device for up to 60 days, so returning users can continue in one click.

Qiscus sends you to your identity provider sign in there as usual.

3. After a successful sign-in, you're brought back to Qiscus and into the dashboard.

SSO with Microsoft Entra ID

This guide connects Qiscus Omnichannel sign-in to Microsoft Entra ID (formerly Azure Active Directory) using SAML 2.0. When you're done, your team signs in to Qiscus with their company Microsoft accounts.

Before you start

• An admin account in Qiscus Omnichannel.

• A Microsoft Entra account with the Cloud Application Administrator, Application Administrator, or Global Administrator role.

• Every user who will sign in with SSO already exists in Qiscus, with exactly the same email as the Email field of that user in Entra. The Email field is not the same as the User Principal Name (UPN): check the Email field.

Step 1 — Qiscus: get the connection details

1. Go to Settings and select Single Sign-On.

2. In Set your workspace, fill in the Workspace: the short name your team types when signing in, for example your-company. When it shows as available, select Next.

3. In Copy details to your IdP, copy the ACS URL and the Entity ID (SP), then select Next. They look like this:

Keep this page open. You come back to it in Step 3.

Step 2 — Microsoft Entra: create a SAML application

1. Sign in to the Microsoft Entra admin center and go to Entra ID → Enterprise apps → New application → Create your own application.

2. Enter a name, for example Qiscus Omnichannel, choose Integrate any other application you don't find in the gallery (Non-gallery), then select Create.

3. In the new application, go to Single sign-on and select SAML.

4. On the Basic SAML Configuration card, select Edit, fill in the two fields below, leave the other fields empty, and select Save:

   • Identifier (Entity ID): the Entity ID (SP) from Qiscus.

   • Reply URL (Assertion Consumer Service URL): the ACS URL from Qiscus.

5. On the Attributes & Claims card you don't need to change anything. Make sure the emailaddress claim takes its value from user.mail, and that every user who will sign in has the Email field filled in.

6. Go to Users and groups → Add user/group and assign the users or groups that are allowed to sign in to Qiscus.

7. On the SAML Certificates card, copy the App Federation Metadata Url.

Step 3 — Qiscus: connect to Microsoft Entra

1. Back in Settings → Single Sign-On, in Add IdP metadata, paste the App Federation Metadata Url and select Connect & test. Qiscus reads the metadata from Microsoft Entra.

2. In Map attributes, set the SAML attribute for the email field to the full URI below, then select Next:

3. In Test & enable, select Test connection. When Connection verified appears, select Finish setup.

Step 4 — Sign in with Microsoft

1. Open the Qiscus login page and select Log in with SSO.

2. Type your Workspace.

3. Sign in with your Microsoft account. You land in the Qiscus Inbox.

Troubleshooting

Good to know

• Multi-factor authentication (MFA) is handled by Microsoft Entra, not by Qiscus.

• Signing in with a Qiscus email and password still works while SSO is on.

• New users must be created in Qiscus first before they can sign in with SSO.

• Entra's signing certificate is valid for 3 years. When you activate a new certificate in Entra, at the same time paste the App Federation Metadata Url again in Settings → Single Sign-On and save. Until the metadata is updated, SSO sign-in fails.