Admin troubleshooting

When someone can’t sign in, an invite doesn’t land, or a custom domain won’t go live, the cause is almost always one of a handful of known things — and each has a quick, specific fix. This page is the admin’s first stop: a fast diagnostic checklist, then a symptom-by-symptom guide for the issues you’ll actually hit.

It covers the customer-facing problems an administrator can resolve: sign-in and SSO failures, “organization not set up” errors, invites, and domain/certificate issues. For setting these things up in the first place, see Connect your identity provider (SSO) and Branding and custom domain.

Who this page is for

You’re an IT or workspace administrator. You don’t need to be an engineer. Some fixes are yours to make directly (roles, invites); a few touch your identity provider or DNS, and a small number need your SUPERWISE contact to confirm a setting on your workspace. Each item below says clearly which is which.

Start here: a 60-second triage

Before diving into a specific symptom, answer these three questions. They narrow almost every problem to the right section.

1. Does the user reach your provider’s login screen at all?
   • No, they see a Chat error first → the connection isn’t applied or configured. Go to Sign-in won’t start.
   • Yes, they log in, then get bounced back with an error → it’s a redirect or claim problem. Go to Login starts but fails.
2. Do they log in successfully but then can’t get in (access / “not provisioned” error)? → Go to Organization not set up.
3. Are they in, but with the wrong access — too much or too little? → Go to Wrong access level.

If you’re not sure where a problem fits, work top to bottom — the sections are ordered the way a sign-in actually happens.

Before you troubleshoot

Have these on hand. Most fixes need one or two of them.

You’ll want	Where it comes from
Admin access to your identity provider	Your Okta / Entra ID / Auth0 / Frontegg console
Your workspace’s exact redirect (callback) and logout URLs	Your SUPERWISE contact — the most common fix is matching these character for character
An administrator role in Chat	So you can view users, assign roles, and read the audit log
A test account	A real user you can reproduce the issue with, in a fresh private/incognito window

Reproduce in a clean window first

Many “it’s broken” reports are stale cookies or a half-finished previous session. Before anything else, have the user try again in a fresh incognito/private window. If it works there, the fix is simply clearing cookies for the Chat address.

Sign-in won’t start

The user opens Chat and sees an error before ever reaching your provider’s login page — they never get the chance to type their password.

Most likely cause: the SSO connection details aren’t fully applied, or one is missing.

1. Confirm all three connection values are entered for your workspace: the issuer URL, the client ID, and the client secret. A missing or mistyped secret is the usual culprit.
2. If you just saved them, wait a moment and retry — the connection picks up new details shortly after saving.
3. Confirm you’re opening the correct workspace address. A typo’d or outdated URL can land on a page with no sign-in configured.
4. Still stuck? Ask your SUPERWISE contact to confirm the connection is active on your workspace and that the issuer URL is reachable.

Note

Once your connection is in place, Chat validates every sign-in against your provider’s published signing keys automatically and keeps up with key rotations on its own — there’s nothing for you to refresh or re-sync after the initial setup.

Login starts but fails (redirect or token errors)

The user reaches your provider, signs in, and is sent back to Chat — but lands on an error like a redirect mismatch or “state mismatch.”

By far the most common cause: the redirect URI registered in your identity provider doesn’t exactly match Chat’s callback URL.

1. Get your workspace’s exact callback URL from your SUPERWISE contact. It’s specific to your workspace, so use the value they give you rather than guessing the path.
2. In your provider’s application settings, compare it to the allowed redirect URI(s) character for character: the https://, the hostname, and the full path including any trailing segment. A single mismatched character breaks the round trip.
3. Paste the exact value in, save, then have the user retry in a fresh private window.
4. If your provider also has a logout / sign-out URL, confirm that matches too — a logout mismatch can leave users unable to start a clean new session.

Symptom	Likely cause	Fix
”Redirect URI mismatch” / “state mismatch”	Callback URL doesn’t match your provider	Match the redirect URI exactly (step 2 above), then retry in a clean window
”Invalid token” / token rejected after login	Audience or issuer mismatch	For Auth0, confirm the audience / API identifier is set on the connection — Auth0 requires it. Confirm the issuer URL matches your provider’s base address.
Login loops back to the login page	Stale cookies or a half-finished session	Clear cookies for the Chat address and retry in incognito

Auth0 needs an audience

If your provider is Auth0 and logins fail with a token error after a successful sign-in, the missing piece is almost always the audience parameter. Auth0 won’t issue a usable token for an API without it. Add your application’s API identifier to the connection and retry.

Organization not set up (tenant not provisioned)

The user signs in successfully at your provider, comes back to Chat, and is then turned away with an access error — often referencing that their organization isn’t set up or not provisioned.

This is expected, safe behavior, not a bug. For production security, Chat defaults to invite-only: a person can sign in only if they belong to an organization that has already been set up. Unknown organizations are turned away by design, so a stray or misconfigured account can’t quietly create access.

What to do, in order:

1. Confirm the user is in a recognized organization. Check that their account is part of an organization (tenant) that’s been provisioned on your workspace. If your whole org is new, the organization itself may not be set up yet — contact your SUPERWISE contact to provision it.
2. Check the organization claim is reaching Chat. If a user from a real, provisioned org still gets turned away, the token may not be carrying the organization claim Chat reads. Re-confirm which claim your provider uses (tenantId for Frontegg, org_id for Auth0, or your chosen claim for Entra ID / Okta) and that it’s mapped correctly. See Connect your identity provider, step 2.
3. For onboarding a brand-new organization, ask your SUPERWISE contact whether your workspace should keep the default invite-only posture (recommended) or enable automatic provisioning for first-time sign-ins. Invite-only with provider-side group control is the recommended production setup.

Keep invite-only on in production

We recommend leaving Chat invite-only and controlling access through your identity provider’s group assignments. It means you decide exactly who gets in, and a new or misconfigured account can never self-provision its way to access.

Wrong access level after login

The user is in, but can do too much or too little — an everyday member with admin controls, or an admin who can’t see Settings.

In Chat, a user’s access comes from the roles claim your identity provider emits, mapped to a role in Chat. Group membership in your provider becomes access in Chat, and you can also set a role directly inside Chat.

1. Check the user’s group membership in your identity provider. If they should be an admin, confirm they’re in the group you use for admins.
2. Confirm the group is emitted in the roles claim and that the claim is mapped (see Connect your identity provider, step 3). If the roles claim isn’t mapped, everyone arrives with a baseline role regardless of their groups.
3. Or set the role directly in Chat. You can assign the right role to the user in Chat without changing your provider. See Users and roles for the full hierarchy and what each role can do.

Why you can’t grant a role above your own

Chat won’t let an administrator assign a role more powerful than their own — this is a deliberate safeguard against accidental or malicious privilege escalation. If you need to grant a high-level admin role and the option is greyed out, ask someone with a higher administrator role (or your SUPERWISE contact) to make the assignment.

Invites and adding people

How new people get added depends on how your workspace is set up.

• With SSO and group-based access (recommended): you don’t send Chat invites at all. Add the person to the right group in your identity provider; the next time they sign in, they arrive in the correct organization with the access their group grants. This is the cleanest path and follows your existing joiner/mover/leaver process.
• Adding within Chat: an administrator can manage members and roles directly in Settings. If a teammate you added still can’t get in, the cause is almost always one of the two above — their organization isn’t recognized (Organization not set up) or their role/group isn’t mapped (Wrong access level).

Symptom	Likely cause	Fix
Added someone but they can’t sign in	Their org isn’t provisioned (invite-only)	Confirm the org is set up; see Organization not set up
Invited user lands with no access	Roles claim not mapped, or not in any group	Map the roles claim, or set their role in Chat (Users and roles)
New hire can’t see anything they should	Group assignment in your provider missing	Add them to the right provider group; access follows on next sign-in

Domain and certificate issues

Problems reaching Chat at your custom domain (chat.yourcompany.com), or the domain refusing to verify.

A custom domain needs two things in place before it goes live: a DNS record pointing your hostname at SUPERWISE, and a valid TLS certificate covering that exact hostname. The domain activates only when both are correct.

1. Confirm the DNS record matches exactly what SUPERWISE provided — typically a CNAME to a SUPERWISE target. A trailing typo or the wrong record type will block verification.
2. Give DNS time to propagate. Changes usually take effect in minutes but can take up to a few hours depending on your DNS provider’s TTL.
3. Check the certificate covers the exact hostname. The certificate must match the full hostname you’re activating (chat.yourcompany.com), not a parent domain only.
4. Once DNS resolves and the certificate is valid, the domain verifies and goes live. Update bookmarks and internal links to the new address.

Caution

A custom domain is a Business Plus / Enterprise feature and involves your IT/DNS team. If the controls are locked, check your plan; if verification stalls, the cause is nearly always DNS not yet propagated or a certificate that doesn’t cover the exact hostname. Full setup steps are in Branding and custom domain.

Worked example: a new hire can’t sign in

A new team member, Dana, reports “I can’t get into Chat.” Here’s the fast path to a fix:

1. Triage. Ask Dana what she sees. She reaches the company login page fine, signs in, then gets an access error mentioning her organization. That points straight at Organization not set up or a missing role.
2. Reproduce cleanly. You open Chat in an incognito window and sign in as your own test account — that works. So the connection itself is healthy; the issue is specific to Dana.
3. Check her org and group. In your identity provider, you confirm Dana is in the company directory but was never added to the Chat Users group. Because access flows from the roles claim, she arrived without the access her teammates have.
4. Fix at the source. You add Dana to the Chat Users group in your provider. (If you’d rather not wait for a provider sync, you can also assign her role directly in Chat — see Users and roles.)
5. Verify. Dana signs in again in a fresh window, lands in the right organization, and sees exactly what her role allows. Done — no SUPERWISE ticket needed.

The pattern generalizes: triage → reproduce clean → fix at the right layer (provider group, Chat role, or DNS) → verify in a clean window.

When to contact SUPERWISE

Most admin issues are yours to fix. Reach out to your SUPERWISE contact when:

• You need your workspace’s exact redirect / logout URLs or the DNS / certificate target for a custom domain.
• A new organization needs provisioning on your workspace.
• Sign-in fails for everyone even though your provider config looks correct (this points at a workspace-side setting only SUPERWISE can confirm).
• You want to change your workspace’s provisioning posture (e.g. invite-only vs. automatic).

When you reach out, include: the symptom, whether it affects one user or everyone, your identity provider, and whether the user reaches your login screen before failing. That’s everything needed to resolve it quickly.

Related pages

• Connect your identity provider (SSO) — set up and map your provider’s claims; the source of most sign-in fixes.
• Users and roles — the role hierarchy and how to set access directly in Chat.
• Branding and custom domain — full setup for the domain and certificate steps referenced above.
• Audit and usage — review sign-ins, access changes, and activity when you need a record of what happened.