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

# API-Schlüssel erstellen und verwalten

> Erstellen, begrenzen, deaktivieren, reaktivieren, rotieren und löschen Sie JobHandy API-Schlüssel im Administrationsbereich.

API-Schlüssel werden im JobHandy-Administrationsbereich verwaltet. Diese Seite erklärt, wer Zugangsdaten verwalten darf, wie der Geltungsbereich festgelegt wird und wie Zugriffe entzogen oder wiederhergestellt werden.

<Info>
  Öffnen Sie die [JobHandy-Administration](https://app.jobhandy.io/admin). Für die Verwaltung von API-Schlüsseln ist mindestens eine der folgenden Portalberechtigungen erforderlich: **IT**, **HR** oder **Company-Admin**.
</Info>

## Getrennte Berechtigungsmodelle

Portalberechtigungen und der Geltungsbereich eines API-Schlüssels sind voneinander getrennte Kontrollen:

| Kontrolle                          | Gilt für                             | Zweck                                                                           |
| ---------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------- |
| Portalberechtigung                 | Einen angemeldeten JobHandy-Benutzer | Legt fest, wer die **IT-Einstellungen** öffnen und API-Schlüssel verwalten darf |
| Geltungsbereich des API-Schlüssels | Server-zu-Server-Zugangsdaten        | Legt fest, auf welche Tenants und Divisionen die Integration zugreifen darf     |

Ein Benutzer, der einen API-Schlüssel erstellen darf, gewährt ihm nicht automatisch Zugriff auf jedes Unternehmen. Der bei der Erstellung ausgewählte Geltungsbereich ist die wirksame API-Grenze.

## API-Schlüsselverwaltung öffnen

Öffnen Sie im Administrationsbereich **IT-Einstellungen** und wählen Sie den Tab **API-Schlüssel**. Die Tabelle zeigt **Name**, **Geltungsbereich**, **Status**, **Erstellt am** und **Aktionen** für jeden API-Schlüssel.

<Frame>
  <img src="https://mintcdn.com/jobhandy/eYWivtukLSxRL1Cd/images/api-keys/api-key-list-de.png?fit=max&auto=format&n=eYWivtukLSxRL1Cd&q=85&s=12c5f1a344f125d9b2607a19f2104f5f" alt="JobHandy IT-Einstellungen mit dem Tab API-Schlüssel, vorhandenen API-Schlüsseln und der Schaltfläche API-Schlüssel anlegen" width="1222" height="785" data-path="images/api-keys/api-key-list-de.png" />
</Frame>

## API-Schlüssel erstellen

Klicken Sie auf **API-Schlüssel anlegen** und vergeben Sie einen aussagekräftigen Namen für das verwendende System oder die Integration.

Empfohlenes Benennungsschema:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
<System>-<Zweck>-<Umgebung>
```

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
HR-Middleware-Mitarbeitersync-Produktion
Payroll-Connector-Exporte-Produktion
```

Legen Sie anschließend fest, auf welche Unternehmen und Divisionen der API-Schlüssel zugreifen darf.

<Frame>
  <img src="https://mintcdn.com/jobhandy/eYWivtukLSxRL1Cd/images/api-keys/api-key-create-de.png?fit=max&auto=format&n=eYWivtukLSxRL1Cd&q=85&s=694108affe08215f5d247e7e86c3d95a" alt="Dialog API-Schlüssel anlegen mit Name und Auswahl des Geltungsbereichs" width="1223" height="783" data-path="images/api-keys/api-key-create-de.png" />
</Frame>

### Auswahl des Geltungsbereichs verstehen

| Option                          | Ergebnis                                                                      |
| ------------------------------- | ----------------------------------------------------------------------------- |
| **Alle auswählen**              | Schließt die vollständige Divisionsstruktur des ausgewählten Unternehmens ein |
| **Nur Auswahl (Blätter)**       | Schließt ausschließlich die explizit ausgewählten Enddivisionen ein           |
| **Unterdivisionen einbeziehen** | Schließt eine ausgewählte Division und deren untergeordnete Divisionen ein    |

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    C[Ausgewähltes Unternehmen] --> S[Vertrieb]
    C --> O[Operations]
    S --> E[Enterprise]
    S --> M[SMB]

    ALL[Alle auswählen] -.-> C
    SUB[Unterdivisionen einbeziehen: Vertrieb] -.-> S
    LEAF[Nur Auswahl: Enterprise] -.-> E
```

Im abgebildeten Beispiel gilt **Alle auswählen**. Der API-Schlüssel erhält damit Zugriff auf die vollständige Unternehmensstruktur der ausgewählten Organisation.

<Warning>
  Verwenden Sie den kleinstmöglichen erforderlichen Geltungsbereich. Erstellen Sie getrennte API-Schlüssel für Systeme mit unterschiedlichen Aufgaben, Unternehmen oder betrieblichen Verantwortlichen.
</Warning>

Klicken Sie auf **Hinzufügen**, um den ausgewählten Geltungsbereich zu übernehmen, und anschließend auf **Speichern**, um den API-Schlüssel zu erstellen.

## Erzeugten API-Schlüssel kopieren und sicher speichern

JobHandy zeigt den vollständigen API-Schlüssel unmittelbar nach der Erstellung an. Er ist sofort aktiv und kann im Request-Header `X-API-Key` verwendet werden.

<Frame>
  <img src="https://mintcdn.com/jobhandy/eYWivtukLSxRL1Cd/images/api-keys/api-key-created-de.png?fit=max&auto=format&n=eYWivtukLSxRL1Cd&q=85&s=3013c42b189e89fea097e4dfafd5ca55" alt="Bestätigung nach der Erstellung eines JobHandy API-Schlüssels" width="1222" height="784" data-path="images/api-keys/api-key-created-de.png" />
</Frame>

<Warning>
  Kopieren Sie den API-Schlüssel sofort und speichern Sie ihn in einem Secret Manager. API-Schlüssel gehören nicht in Quellcode, Browseranwendungen, öffentliche Repositories, Tickets, Screenshots oder Anwendungslogs.
</Warning>

## Aktiven API-Schlüssel prüfen

Nach dem Schließen des Dialogs erscheint der API-Schlüssel mit dem Status **AKTIV**. Über **Deaktivieren** kann der Zugriff widerrufen werden, ohne den API-Schlüssel zu löschen.

<Frame>
  <img src="https://mintcdn.com/jobhandy/eYWivtukLSxRL1Cd/images/api-keys/api-key-active-de.png?fit=max&auto=format&n=eYWivtukLSxRL1Cd&q=85&s=1e92ff5bb1e12f383d28cecb9cef0fec" alt="Neu erstellter JobHandy API-Schlüssel mit dem Status AKTIV und der Aktion Deaktivieren" width="1223" height="785" data-path="images/api-keys/api-key-active-de.png" />
</Frame>

## Deaktivieren, reaktivieren oder löschen

Klicken Sie auf **Deaktivieren**, wenn der Zugriff entzogen werden muss. Die Deaktivierung gilt für nachfolgende geschützte Anfragen. Anschließend wird der API-Schlüssel mit dem Status **INAKTIV** angezeigt und kann über **Reaktivieren** wieder aktiviert oder über **Löschen** endgültig entfernt werden.

<Frame>
  <img src="https://mintcdn.com/jobhandy/eYWivtukLSxRL1Cd/images/api-keys/api-key-inactive-de.png?fit=max&auto=format&n=eYWivtukLSxRL1Cd&q=85&s=f7de06f2fac3cd91e44b2769c34cff2d" alt="Inaktiver JobHandy API-Schlüssel mit den Aktionen Reaktivieren und Löschen" width="1222" height="782" data-path="images/api-keys/api-key-inactive-de.png" />
</Frame>

| Aktion           | Verwenden, wenn                                                                    | Ergebnis                                                          |
| ---------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Deaktivieren** | Der Zugriff sofort enden, später aber möglicherweise wiederhergestellt werden soll | Der API-Schlüssel authentifiziert keine geschützten Anfragen mehr |
| **Reaktivieren** | Derselbe API-Schlüssel wieder verwendet werden soll                                | Der inaktive API-Schlüssel erhält wieder den Status **AKTIV**     |
| **Löschen**      | Der API-Schlüssel endgültig außer Betrieb genommen wird                            | Der API-Schlüssel kann nicht mehr reaktiviert werden              |

## API-Schlüssel ohne Unterbrechung rotieren

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant Admin as Unternehmensadministrator
    participant Portal as JobHandy-Administration
    participant Secrets as Secret Manager
    participant Client as Integration
    participant API as JobHandy API

    Admin->>Portal: Ersatzschlüssel mit gleichwertigem Geltungsbereich erstellen
    Portal-->>Admin: Ersatzschlüssel einmalig anzeigen
    Admin->>Secrets: Ersatzschlüssel speichern
    Secrets-->>Client: Neue Zugangsdaten bereitstellen
    Client->>API: Geschützte Anfrage prüfen
    API-->>Client: Erfolg + X-Request-ID
    Admin->>Portal: Alten API-Schlüssel deaktivieren
    Admin->>Portal: Alten API-Schlüssel nach Prüfung löschen
```

Deaktivieren Sie den alten API-Schlüssel erst, nachdem der Ersatzschlüssel in jeder aktiven Instanz der Integration mindestens eine geschützte Anfrage erfolgreich abgeschlossen hat.

<Card title="Detaillierter Rotationsablauf" icon="rotate-cw" horizontal href="/de/guides/rotate-api-keys">
  Verwenden Sie das Betriebs-Runbook für Vorbereitung, Rollout, Prüfung, Rollback und endgültige Außerbetriebnahme.
</Card>

## Lebenszyklus eines API-Schlüssels

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
stateDiagram-v2
    state "AKTIV" as ACTIVE
    state "INAKTIV" as INACTIVE
    state "GELÖSCHT" as DELETED

    [*] --> ACTIVE: Anlegen
    ACTIVE --> INACTIVE: Deaktivieren
    INACTIVE --> ACTIVE: Reaktivieren
    INACTIVE --> DELETED: Löschen
    DELETED --> [*]
```

Weitere Informationen zu Request-Headern und Authentifizierungsfehlern finden Sie unter [Authentifizierung](/de/get-started/authentication).