Roles and access control

GVenta Help Desk has two entirely separate identity systems that never overlap: staff accounts, which carry a role, and client accounts, which belong to your customers’ contacts and are scoped to a single company. This page explains both, and the ways each can authenticate.

Staff roles

Every staff account has one of four roles. Each role carries an explicit permission set, listed here using the permission names the API reports.

Role	Description	Permissions
Super Admin	Full system access	users.create, users.read, users.update, users.delete, tickets.create, tickets.read, tickets.update, tickets.delete, tickets.assign, tickets.close, kb.create, kb.read, kb.update, kb.delete, kb.publish, settings.read, settings.update, audit.read, sla.manage, tags.manage
Agent	Front-line ticket handling	tickets.create, tickets.read, tickets.update, tickets.assign, tickets.close, kb.read, tags.read, users.read
Viewer	Read-only	tickets.read, kb.read, tags.read
KB Editor	Knowledge base ownership	tickets.read, kb.create, kb.read, kb.update, kb.delete, kb.publish, tags.read

A few practical consequences of these sets:

• Only Super Admins can delete tickets, manage users, change settings, read audit logs, or manage SLA policies.
• Agents can create, update, assign and close tickets but cannot delete them, and can read the knowledge base but not edit it.
• KB Editors own the knowledge base, including publishing, and can read tickets but not change them.
• Viewers can look at tickets and articles and nothing else.
• Reports are available to Super Admin, Agent and Viewer roles. Other roles see an “Access Restricted” panel.
• API tokens can be created only by Super Admins and Agents.

Roles are assigned when an administrator creates or edits a user under Settings, User Management (see Settings and administration).

Roles are queryable at runtime

You never need to hard-code these rules in an integration or a custom front-end. The API exposes the role definitions and lets a caller ask about its own effective permissions:

• GET /api/roles returns all roles with display names, descriptions and permission lists.
• GET /api/roles/me/permissions returns the caller’s effective permissions.
• POST /api/roles/me/check-permission tests a single permission, and POST /api/roles/me/check-permissions tests several at once.

See the API reference for request and response details.

AI agent accounts

A staff user can be flagged as an AI agent. AI accounts are badged with a robot icon throughout the interface so colleagues always know when they are looking at automated work. Each AI account has two independent capability switches:

Switch	What it allows
Can reply to customer	The account may send customer-facing replies.
Can suggest answers	The account may post internal notes with suggested answers for a human to review.

These boundaries are enforced by the server, not by the AI’s good behavior. When an AI account posts to a ticket:

• If it does not have Can reply to customer and attempts a customer-facing reply, the request is refused with a 403 response.
• If it has neither switch, it is refused even for internal notes.

Why it matters: You can safely give an AI assistant a seat, drafting internal suggestions only, or replying to customers directly, with the boundary enforced by the server rather than by trust.

Client identities

Your customers’ contacts authenticate separately from staff, through the client portal at https://your-instance.example/clientarea. When a contact signs in they receive a token stamped as a client token and tied to exactly one company. Every client-facing query is filtered by that company, so a contact can only ever see their own company’s tickets, attachments and knowledge base content.

If a contact attempts to reach a ticket that belongs to a different company, the attempt is written to the audit trail as an unauthorized_access event and the response is a generic “not found”. The portal never reveals that another company’s ticket exists.

Contact accounts also include:

• Brute-force protection. Failed sign-in attempts are counted, and an account can be locked until a set time.
• Password reset tokens with an expiry, used by the client portal’s forgot-password and account-activation flows.
• A password must change flag, which forces the contact to choose a new password on their next sign-in.

Registration, account claiming and the ticket-number verification path are described in Client portal.

Authentication mechanisms

The application accepts several ways of proving who you are. Which one applies depends on whether you are using the browser interface, the API, or the client portal.

Mechanism	Used by	How it works
Browser session	Staff pages in the browser	After you sign in, a server-side session is established. The session is created only from a token that the server has re-validated itself, never from data supplied by the browser, and the session identifier is regenerated at that point. Sessions expire after a configurable time, 7,200 seconds (two hours) by default.
JWT bearer token	The API and in-page interactions	Signing in through POST /api/auth/login returns an access token and a refresh token. Access tokens expire after 60 minutes by default; refresh tokens last 30 days by default and are stored on the server along with device information. The token’s issuer and audience are verified on every request.
API key	Service accounts and integrations	A 64-character hexadecimal token created under Settings, API Tokens or via the API. Send it in an X-API-Key header or as Authorization: Bearer. Keys can be given an expiry of 1 to 365 days, or none. The application stores only a hash of the key, and the plaintext is shown exactly once, at creation.
Flexible	Selected ticket endpoints	The endpoint tries a JWT first and falls back to an API key, so a single endpoint serves both the browser interface and an integration.
Client	Client portal endpoints	A client token, with a deliberate fallback to a still-valid browser session. This covers a second browser tab where the per-tab token is absent, and an expired token that outlives a session which is still valid.

Requests authenticated by a browser session or a JWT must include a CSRF token on any state-changing call. API-key requests are exempt, because an attacker cannot forge a custom header from another site, which keeps server-to-server integrations simple. Rate limiting applies to every call, keyed by user when authenticated and by IP address otherwise. See API getting started and Security and storage.

Token revocation and signing out everywhere

• Sign out revokes the token you presented by adding it to a blacklist, so it cannot be reused even before it expires.
• A sign out everywhere path revokes all of a user’s tokens at once. Use it when a device is lost or an account may be compromised.
• Individual API keys can be revoked (kept on record but disabled) or deleted from Settings, API Tokens.
• Expired blacklist entries are purged on a schedule by a background job, described in Background jobs.