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

# Authentifizierung

> Anmeldung an der NETZFABRIK API per JWT (Login mit E-Mail und Passwort) oder mit einem persönlichen API-Token.

Alle Endpoints außer Login, Registrierung und Passwort-Wiederherstellung erfordern eine Authentifizierung. Du hast zwei Möglichkeiten:

| Verfahren | Header | Geeignet für |
| - | - | - |
| JWT (Bearer) | `Authorization: Bearer <token>` | Interaktive Anwendungen, kurzlebige Sitzungen |
| API-Token | `X-API-TOKEN: <token>` | Skripte, CI/CD, Server-zu-Server |

## Option 1: JWT per Login

Melde dich mit E-Mail und Passwort an und erhalte ein Token-Paar:

```bash theme={null}
curl -X POST https://api.netzfabrik.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "name@example.com", "password": "geheim"}'
```

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "a1b2c3..."
}
```

Das `token` schickst du bei jeder Anfrage im Header `Authorization: Bearer <token>` mit. Es ist zeitlich begrenzt gültig. Mit dem `refresh_token` holst du ein neues Token, ohne das Passwort erneut zu senden:

```bash theme={null}
curl -X POST https://api.netzfabrik.com/auth/token/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "a1b2c3..."}'
```

> [!NOTE]
>
> Ist für dein Konto die Zwei-Faktor-Authentifizierung aktiv, liefert `POST /auth/login` statt des vollständigen Token-Paars ein Vorab-Token (`auth_scope: mfa_pending`). Bestätige damit den zweiten Faktor über `POST /auth/2fa/verify` (TOTP- oder Wiederherstellungscode) und erhalte anschließend das reguläre Token-Paar. Alternativ kannst du dich mit einem Passkey über `POST /auth/passkeys/login/options` und `POST /auth/passkeys/login/verify` anmelden.

## Option 2: Persönlicher API-Token

Für Automatisierungen legst du einen dauerhaften API-Token an. Dafür brauchst du einmalig ein JWT:

```bash theme={null}
curl -X POST https://api.netzfabrik.com/user/api-tokens \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"description": "Deploy-Pipeline"}'
```

Die Antwort enthält den Token im Feld `token`. Er wird nur bei der Erstellung im Klartext ausgegeben, speichere ihn also sicher. Danach nutzt du ihn im Header `X-API-TOKEN`:

```bash theme={null}
curl https://api.netzfabrik.com/domains \
  -H "X-API-TOKEN: $API_TOKEN"
```

Über `GET /user/api-tokens` siehst du alle Tokens deines Benutzers, mit `DELETE /user/api-tokens/{id}` widerrufst du einen Token sofort.

## Berechtigungen

Ein Token handelt immer im Namen des Benutzers, der ihn erzeugt hat, und hat dieselben Rechte wie dieser Benutzer im Kundenpanel. Ressourcen anderer Kunden sind nicht sichtbar und liefern `404 Not Found`.

> [!WARNING]
>
> Behandle Tokens wie Passwörter. Lege sie nie in Client-seitigem Code oder öffentlichen Repositories ab. Verwende für jede Anwendung einen eigenen API-Token, damit du ihn einzeln widerrufen kannst.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.