> ## Documentation Index
> Fetch the complete documentation index at: https://developers.jobhandy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Terminology

> Use consistent definitions for companies, tenants, divisions, users, credentials, scope, and resources.

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.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    UI[Company in administration portal] -->|technical representation| TEN[Tenant in API]
    TEN --> D1[Division]
    TEN --> D2[Division]
```

Do not assume a company name is a stable technical identifier. Persist the tenant ID used by the API.

## Two independent authorization layers

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    USER[Portal user] --> PERM[IT / HR / Company-Admin]
    PERM --> MANAGE[May manage API keys]

    KEY[API key] --> SCOPE[Selected tenant and division scope]
    SCOPE --> ACCESS[May access matching API resources]
```

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.