Terminology - JobHandy Developers

Use these terms consistently in implementation, logging, support, and documentation.

Term	Definition
Company	Business-facing organization shown in the JobHandy administration portal
Tenant	Technical API representation of an organization; identified by a tenant ID
Division	Hierarchical organizational unit owned by one tenant
Portal user	Human user who signs in to the JobHandy administration portal
Portal permission	Human authorization such as IT, HR, or Company-Admin
API key	Server-to-server credential sent in `X-API-Key`
API-key scope	Tenants and divisions that the key is allowed to access
Tenant context	One selected tenant for a request, commonly supplied with `X-Tenant-ID`
Resource ID	Opaque identifier of an employee, order, incident, division, attachment, or export document
Dry run	Validation of a supported write without the documented persistence and side effects
Request ID	UUID v4 or v7 used to correlate one request attempt; not an idempotency key

Company and tenant

In the user interface, administrators select companies and organizational areas. In the API, the corresponding technical boundary is represented as a tenant ID. Do not assume a company name is a stable technical identifier. Persist the tenant ID used by the API.

Two independent authorization layers

A portal user may be permitted to create keys, while each key still has its own limited API scope.

Tenant and division

A tenant owns its division hierarchy.
A division can have a parent division or be a root division.
An employee can have a tenant and an optional division assignment.
A division ID cannot be used to grant access outside the key’s scope.
Public employee updates cannot transfer an assigned employee to another tenant.

Attempt, request, and retry

A logical operation may contain multiple HTTP attempts. Generate a new X-Request-ID for each attempt and link the attempts in your own logs. Reusing an ID does not make the operation idempotent.

Last modified on August 27, 2026