🧑‍💼 REST API: Analysts

The usage guide for analyst provisioning in the REST API (3.5.0): how an identity source - an HR feed, or the OIDC provider that decides who is staff - creates analysts, keeps their details in step, sets what they may do, and takes it away when they leave. It mirrors the interactive documentation at System → API → Documentation. Built from a design contributed by @Kraleemil (PR #174).

[!NOTE] New to the API? The basics table on REST API: Tickets covers the base URL, authentication, the response envelope, error codes, rate limits and PATCH semantics. They are the same across all modules.

What's distinctive about analysts:

🔐 Administrator keys only	Every write (POST /analysts, PATCH /analysts/{id}, PATCH /analysts/{id}/access) needs a key that acts as a System administrator and is scoped to all companies. Anything else gets a 403. In the app only administrators manage analysts, and a key is held to the same rule, so it can never grant its own analyst more than it has. Reads need only the permission.
🚫 New analysts start with nothing	No modules, no companies (on a multi-company install), not an administrator, and a local password nobody knows - they sign in through auth_provider_id. Access is granted explicitly.
🧩 Access in four parts	Admin, modules, companies and capabilities. Each list replaces that part; anything you leave out stays as it is. Keys are checked, so a typo is a 422, never silently dropped.
🛡️ Locks you can't break	You can't deactivate or demote the key's own analyst, and you can't remove or deactivate the last active administrator (409) - the same guard System → Analysts has.

🚀 Quick start

B="https://your-server/api/v1"; K="Authorization: Bearer fitsm_…"; J="Content-Type: application/json"

# Is Sam already here (even if deactivated)?
curl -s -H "$K" "$B/[email protected]&include_inactive=1"

# Create Sam - signs in through SSO provider 1
curl -s -H "$K" -H "$J" -X POST "$B/analysts" -d '{"email":"[email protected]","full_name":"Sam Jones","auth_provider_id":1}'

# Tickets and Knowledge, for company 4, plus the right to manage ticket settings
curl -s -H "$K" -H "$J" -X PATCH "$B/analysts/42/access" -d '{
  "all_modules": false, "modules": ["tickets", "knowledge"],
  "all_companies": false, "companies": [4],
  "capabilities": ["tickets.manage"]
}'

# Sam left the staff team
curl -s -H "$K" -H "$J" -X PATCH "$B/analysts/42" -d '{"is_active": false}'

Endpoints

Method	Path	Permission
🟢 GET	/analysts	analysts.read	Active analysts (id, name, email, is_active). ?email= finds one by address (ignoring case); ?include_inactive=1 adds deactivated ones.
🔵 POST	/analysts	analysts.create	email (required, unique), full_name, username (made unique), auth_provider_id. 201.
🟢 GET	/analysts/{id}	analysts.read	One analyst, active or not.
🟠 PATCH	/analysts/{id}	analysts.update	Any of full_name, email, is_active, auth_provider_id. Setting auth_provider_id switches off Follow team.
🟢 GET	/analysts/{id}/access	analyst_access.read	Their own grants, plus effective.
🟠 PATCH	/analysts/{id}/access	analyst_access.manage	Any of is_admin, all_modules, modules, all_companies, companies, capabilities.

An analyst reads back as:

{ "id": 42, "username": "sam", "name": "Sam Jones", "email": "[email protected]",
  "is_active": true, "is_admin": false, "auth_provider_id": 1,
  "created_at": "2026-10-11T09:00:00Z", "last_login_at": null }

Access

{
  "is_admin": false,
  "all_modules": false, "modules": ["knowledge", "tickets"],
  "all_companies": false, "companies": [4],
  "capabilities": ["tickets.manage"],
  "effective": { "modules": ["knowledge", "tickets"], "companies": [4], "capabilities": ["tickets.manage"] }
}

• modules are module keys (tickets, assets, knowledge …). System is not a module: it comes with is_admin. With all_modules: true the list is kept but not used.
• companies are company ids (GET /companies). With all_companies: true the list is kept but not used. On a single-company install, leave it alone.
• capabilities are RBAC settings capabilities (tickets.manage, assets.leasing …; the full list is in System → Roles). They're held on one role per analyst that the API keeps, named API: Sam Jones. It shows on System → Roles marked API and is read-only there: it can't be edited, deleted or assigned to anyone else, because the next sync would overwrite it. It's deleted with its analyst. Roles you assign by hand and grants that come through teams are never touched.
• effective is what the analyst really ends up with once teams and hand-assigned roles are counted. effective.modules: null means every module. Compare it with your source before you change anything.

Errors

Code	When
403 forbidden	The key doesn't act as an administrator, or is scoped to specific companies (writes only).
404 not_found	No such analyst.
409 conflict	Another analyst already uses that email, or this is the last active administrator.
422 invalid_field / missing_field	An invalid field, an unknown module, company or capability, nothing sent, or the key's own analyst would be deactivated or lose admin.

Not covered (yet)

• Signing in with OIDC claims. Taking the analyst flag and their access from claims at each sign-in (the OIDC twin of LDAP's analyst group) was proposed in PR #174 and isn't built. For now, push changes through these endpoints.
• Open sessions are covered: a deactivated analyst has no modules and isn't an administrator from their next click (Leavers could still sign in).
• Moving a leaver's work, anonymising and deleting happen on screen, not over the API: System → Analysts, the bin icon on their row. PATCH {"is_active": false} is the API's equivalent of Deactivate. See When an analyst leaves.

For developers: see the Analyst provisioning — Developer Guide.