> ## 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.

# Tenant-Scope und Ressourcenzuordnung

> Lösen Sie Tenant-Kontext, Divisionszuordnung und API-Key-Autorisierung eindeutig auf.

Jede geschützte Anfrage wird innerhalb des Tenant- und Divisionsscopes ausgeführt, der dem API-Key zugewiesen ist.

## Scope-Auflösung

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    R[Geschützte Anfrage] --> K{Gültiger aktiver API-Key?}
    K -- Nein --> E1[401 INVALID_API_KEY]
    K -- Ja --> H{X-Tenant-ID gesendet?}
    H -- Ja --> S{Tenant im Key-Scope?}
    S -- Nein --> E2[403 TENANT_NOT_IN_SCOPE]
    S -- Ja --> T[Ausgewählten Tenant verwenden]
    H -- Nein --> I{Kann die Operation genau einen Tenant ermitteln?}
    I -- Ja --> T
    I -- Nein --> E3[TENANT_CONTEXT_AMBIGUOUS]
```

## Collection-Operationen

Collection-Endpoints können bei fehlendem `X-Tenant-ID` alle Tenants im Scope des Keys abfragen. Senden Sie den Header, um die Ergebnisse auf einen autorisierten Tenant einzuschränken.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request GET \
  --url 'https://api.jobhandy.io/v1/employees' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-ID: {{tenantId}}'
```

## Create-Operationen

| Operation             | Angaben zur Zuordnung                                           | Behandlung von Mehrdeutigkeit                                                                     |
| --------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Mitarbeiter erstellen | `X-Tenant-ID` und/oder `divisionId`                             | Die API muss genau einen Tenant und, falls erforderlich, eine zulässige Division bestimmen können |
| Vorfall erstellen     | Mitarbeiterreferenz, optional durch `X-Tenant-ID` eingeschränkt | Der referenzierte Mitarbeiter muss im ausgewählten Kontext zugänglich sein                        |
| Division erstellen    | `X-Tenant-ID`, `parentId` oder eindeutiger Key-Scope            | Die Anfrage schlägt fehl, wenn kein eindeutiger Ziel-Tenant ermittelt werden kann                 |

Bei einem auf Divisionen eingeschränkten Key darf `divisionId` beim Erstellen eines Mitarbeiters nur fehlen, wenn der ausgewählte Tenant genau eine zulässige Division besitzt. Andernfalls muss eine erlaubte Divisions-ID gesendet werden.

## Vorhandene Ressourcen

Bei `GET` und `PATCH` nach ID schränkt `X-Tenant-ID` die Suche ein. Die Ressource und alle referenzierten Zielressourcen müssen über diesen Tenant zugänglich sein.

## Zuordnungsregeln

* `X-Tenant-ID` erweitert niemals den Zugriff.
* Eine Division gehört genau einem Tenant.
* `divisionId` kann einen Mitarbeiter nur innerhalb desselben Tenants zuweisen oder verschieben.
* `divisionId: null` entfernt die Divisionszuordnung; der Mitarbeiter wird dadurch nicht in einen anderen Tenant verschoben.
* Ein Tenant-Transfer eines bereits zugeordneten Mitarbeiters wird durch den öffentlichen Update-Endpoint nicht angeboten.
* Ein Create-Dry-Run kann einen Vorschau-Identifikator zurückgeben, der nicht in späteren Anfragen verwendet werden darf.

## Häufige Fehler

| Fehlercode                     | Typische Ursache                                                      | Korrektur                                                       |
| ------------------------------ | --------------------------------------------------------------------- | --------------------------------------------------------------- |
| `TENANT_CONTEXT_AMBIGUOUS`     | Mehr als ein Tenant kann die Anfrage erfüllen                         | `X-Tenant-ID` oder eine dokumentierte Zuordnungsreferenz senden |
| `EMPLOYEE_PLACEMENT_AMBIGUOUS` | Ein divisionsbeschränkter Scope ergibt keine eindeutige Zuordnung     | Eine zulässige `divisionId` senden                              |
| `TENANT_NOT_IN_SCOPE`          | Der ausgewählte Tenant ist nicht autorisiert                          | Header oder API-Key-Scope korrigieren                           |
| `INVALID_REFERENCE_ID`         | Tenant-, Mitarbeiter- oder Divisions-ID besitzt ein ungültiges Format | Eine von JobHandy zurückgegebene ID verwenden                   |
| `INVALID_REFERENCE`            | Die referenzierte Ressource fehlt oder ist nicht zulässig             | Scope und referenzierte Ressource erneut lesen                  |

<Card title="Begriffe" icon="book-open" horizontal href="/de/concepts/terminology">
  Prüfen Sie die Unterschiede zwischen Unternehmen, Tenant, Division, Portalberechtigung und API-Key-Scope.
</Card>