Overview
The Clarity Jitbit connector reads your helpdesk users, their role tier (Administrator / Technician / Manager), and which ticket categories each technician can work in. It can also create, disable, re-enable, and delete users, and grant or revoke Administrator and category permissions.
What Clarity syncs / writes | Jitbit source | Direction |
|---|---|---|
Users (active) | GET /api/Users?listMode=all | read |
Users (disabled) | GET /api/Users?listMode=disabled | read |
Role: Technician | GET /api/Users?listMode=techs | read |
Role: Administrator | IsAdmin on each user | read |
Role: Manager | IsManager on each user, only when your tenant includes it in the user list | read |
Categories | GET /api/categories | read |
Technicians per category | GET /api/TechsForCategory?id={categoryId} | read |
Create a user | POST /api/CreateUser (no welcome email is sent) | write |
Disable / re-enable a user | POST /api/UpdateUser (disabled=true/false) | write |
Grant / revoke Administrator | POST /api/UpdateUser (isAdmin=true/false) | write |
Grant / revoke a category permission | POST /api/AddCategoryTechPermission · RemoveCategoryTechPermission | write |
Delete a user (permanent) | POST /api/DeleteUser | write |
Authentication is HTTP Basic — a Jitbit username and password sent on every request. There is no OAuth app, no API key screen, and no browser consent or redirect step. Clarity signs in as a dedicated Jitbit user account that you create.
The connector works for both Jitbit SaaS (*.jitbit.com) and self-hosted Jitbit Helpdesk; the only difference is the API Base URL.
Prerequisites
A Jitbit account with the Administrator role, so you can create users and grant the Administrator role.
Your helpdesk’s URL — the address you use to sign in.
HTTPS. Clarity refuses a plain http:// Base URL, because your password is sent with every request. Self-hosted installs must be served over TLS.
Step 1 — Work out your API Base URL
The API lives under /api on your helpdesk address. Enter the full URL, including /api, with no trailing query string.
Deployment | API Base URL |
|---|---|
Jitbit SaaS (cloud) | https://<company>.jitbit.com/helpdesk/api |
Self-hosted, installed at the site root | https://<your-host>/api |
Self-hosted, installed under /helpdesk | https://<your-host>/helpdesk/api |
A quick way to tell: sign in to Jitbit, take the address in your browser up to and including /helpdesk (or up to the host, if there is no /helpdesk), and add /api.
Step 2 — Create a dedicated service account
Create a Jitbit user that exists only for Clarity. Do not reuse a person’s account: Clarity signs in with this password on every request, and the account must stay an Administrator.
In Jitbit, create a new user (for example clarity-sync) and give it a strong password.
Tick Administrator for that user. This is required — every Jitbit user and category API method Clarity calls is administrator-only. A non-admin account signs in successfully but cannot sync.
If your self-hosted helpdesk uses Windows / Active Directory authentication, the username is entered as DOMAIN\username.
⚠️ Needs confirmation with a tenant: the exact menu path for adding a user and the Administrator checkbox can differ between the SaaS and self-hosted editions. The user-edit screen is described in Jitbit’s Edit User documentation. If your helpdesk enforces SSO-only sign-in, make sure this account can still sign in with a local username and password — Basic authentication does not go through SSO.
Step 3 — Enter the credentials in Clarity
In Clarity, add a new Jitbit Helpdesk integration and fill in:
Clarity field | Value |
|---|---|
API Base URL | The URL from Step 1, e.g. https://acme.jitbit.com/helpdesk/api. Must start with https://. |
Service Account Username | The username of the account from Step 2 (DOMAIN\username for Windows-authenticated self-hosted installs). |
Service Account Password | That account’s password (masked, stored encrypted). |
All three fields are required.
⚠️ Check the password before you test. Jitbit blocks the caller’s IP address for 5 minutes after 3 failed sign-ins in a row. Clarity sends exactly one request per Test credentials click and never retries a rejected password, but three wrong attempts will still lock Clarity out for five minutes.
Save, then click Test credentials. The test signs in once (POST /api/Authorization) and checks that the account is an Administrator.
Troubleshooting
Message / symptom | Cause and fix |
|---|---|
Jitbit rejected the username or password (HTTP 401) | Wrong username or password. Fix it before testing again — three failures in a row block Clarity’s IP for 5 minutes. If you have already hit the block, wait 5 minutes. |
Authenticated with Jitbit, but this account is not a helpdesk administrator | The password is correct but the account lacks the Administrator role. Tick Administrator on the service account (Step 2). |
Jitbit denied access for this account (HTTP 403) | Same as above — use an Administrator account. |
The Jitbit API was not found at this base URL (HTTP 404) or Jitbit answered, but not with a user object | The Base URL does not point at the API root. It must end in /api — for SaaS, /helpdesk/api (Step 1). |
Jitbit base_url must be an https URL to the API root | The URL starts with http://, or contains a query string, #fragment, or user:password@. Enter only https://<host>/…/api. |
Sync is slow on large helpdesks | Expected. Jitbit allows 90 API requests per minute and Clarity sends one at a time; throttled pages wait 60 seconds and resume automatically. |
A revoked category permission comes back on the next sync | The technician has that category through a Jitbit user group, not a direct grant. Clarity removes direct grants only — remove the user from the group in Jitbit (see below). |
What Clarity does NOT do
No user groups. Jitbit’s API cannot list groups or their members, so Clarity does not import them. Category access that a technician gets through a group is still visible — Clarity reads each category’s effective technician list — but revoking it from Clarity removes only a direct grant; a group-derived grant stays until you change the group in Jitbit.
No Technician or Manager provisioning. Technician is not a setting in Jitbit — a user becomes a technician by having category permissions, so you grant a category instead. Manager has no API write path. Only Administrator and categories can be granted or revoked.
Manager may not appear. Clarity imports the Manager role only when your tenant’s user list includes the IsManager field; it does not look up each user individually.
No attribute write-back. Clarity does not push names, phone numbers, companies, or departments to Jitbit. Companies and departments are read as user attributes, not entitlements.
Delete is permanent. Jitbit’s delete has no undo. Use deactivate (disable) when you may need the account again.
No welcome email. Users that Clarity creates do not get Jitbit’s welcome email; they are created with their email address as the username.
No tickets, knowledge base, or assets are read.
Need Help?
If you have any problems, contact your customer success team. You can also get in touch with our general support via email, open a support ticket. Our general support team is available Monday - Friday from 8:00 AM - 6:30 PM CST.