API getting started

Everything the GVenta Help Desk interface can do is a documented REST endpoint. The staff and client screens are built on the same API that is offered to you, so anything you see in the application can be scripted, integrated or handed to an AI agent. This page covers the conventions and authentication you need before making your first call.

Conventions

• Base path: https://your-instance.example/api
• Content type: application/json. Endpoints that accept file uploads also accept multipart/form-data.
• Path parameters appear as {id}-style segments, for example /api/tickets/{id}.
• Version header: every response carries X-API-Version: 1.0.

Success shape

{ "success": true, "data": "…", "meta": { "…": "…" }, "message": "…" }

Error shape

Errors return an appropriate HTTP status code with:

{ "success": false, "error": "ERROR_CODE", "message": "Human readable" }

Pagination

List endpoints take limit and offset query parameters. limit is capped at 100. Responses include a meta object with:

Field	Meaning
meta.total	Total number of matching records across all pages
meta.limit	The page size applied
meta.offset	The offset applied
meta.count	The number of records in this response
meta.filters_applied	The filters that were applied to produce the result

Because meta.total is a true filtered count, you can page confidently and show accurate totals.

Authentication

Authentication schemes are declared per route. The endpoint reference marks each endpoint with the scheme it uses.

JWT

Staff users obtain a token pair with POST /api/auth/login, which returns an access token, a refresh token, the user record and a password_must_change flag. Send the access token as:

Authorization: Bearer <access_token>

Access tokens expire after 60 minutes by default. Refresh tokens last 30 days by default, are stored on the server with device information, and are exchanged for a new access token with POST /api/auth/refresh. The token’s issuer and audience are verified on every request. Logging out with POST /api/auth/logout blacklists the presented token; a “sign out everywhere” path exists for compromise response.

When no Authorization header is present, JWT-protected endpoints fall back to the browser session. That is what lets the same endpoints serve both the web interface and external clients.

API key

API keys are for service accounts and integrations. Create one under Settings → API Tokens or with POST /api/tokens, then send it in either of these forms:

X-API-Key: <token>

Authorization: Bearer <token>

Check that a key works with GET /api/tokens/test. Keys are 64-character hex strings, stored only as SHA-256 hashes; the plaintext is shown exactly once, at creation.

Flexible

Some endpoints, chiefly ticket reads and creation, accept either a JWT or an API key. This lets you write one integration and authenticate it whichever way suits.

Client

Client portal endpoints use a client-scoped JWT obtained from POST /api/client/auth/login. These tokens are stamped type: client and scoped to a single company; every client query is filtered by that company. They also fall back to a valid client session when the header is absent. See Client portal for the rules the portal enforces.

Discovering what you are allowed to do

Rather than hard-coding role rules, ask the API: GET /api/roles/me/permissions returns the caller’s effective permissions, and POST /api/roles/me/check-permission tests one. See Roles and access.

CSRF

State-changing requests (anything other than GET and HEAD) that are authenticated by a session or a JWT must include a CSRF token:

X-CSRF-Token: <token>

Obtain one from GET /api/csrf/token when signed in, or GET /api/csrf/session-token for pre-login forms. Tokens are 32 random bytes held with a time-to-live (default 1 hour) and scoped to a user and IP address. GET /api/csrf/config reports whether enforcement is enabled and which header name to use.

API-key-authenticated requests are exempt and need no CSRF token, because an attacker cannot forge a custom header cross-site. This is what makes server-to-server integrations straightforward: an API key and a JSON body are all you need.

Rate limits

Bucket	Applies to	Default
auth	/api/auth/*	Configurable window and count, tighter than the rest
public	Unauthenticated endpoints	Moderate
api	Authenticated endpoints	Generous
—	/api/health, /api/metrics	Exempt

Limits are keyed by user ID when authenticated and by IP address otherwise, and are configurable per environment. Rate limiting fails open if the cache store is unreachable, so an infrastructure problem never turns into a lockout. See Security and storage for the full list of protections applied to every request.

Creating an API token

1. Sign in as a Super Admin or Agent. Only these two roles may create tokens.
2. Go to Settings → API Tokens and use Generate Token, or call POST /api/tokens with a name and an optional expires_in_days between 1 and 365. The interface offers 30 days, 90 days (the default), 1 year or Never.
3. Copy the token from the creation response. It is displayed once; the interface shows a copy-to-clipboard button and a warning that it will not be shown again.

The token list shows each token’s name, creation date, expiry, last-used timestamp and status. You can revoke a token (keeping the record) or delete it. Every API-key authentication, successful or not, is written to the audit log.

Why it matters: The help desk fits your stack instead of the other way around. One key, one JSON body, no CSRF dance, and the same endpoints the interface itself uses.

Explore the endpoints

The full list of endpoints, grouped by area and marked with the authentication scheme each requires, is in the endpoint reference. Worked requests and responses for the most common tasks are in API examples.