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

# Authentifizierung

> Public-API-Anfragen mit dem Header x-api-key authentifizieren.

Sende deinen Organisations-API-Key bei jeder Anfrage mit. Keys gelten für genau eine Organisation und respektieren die Berechtigungen, die du beim Erstellen des Keys festgelegt hast.

## Header

```bash theme={null}
x-api-key: sv_org_your_api_key
```

| Regel           | Detail                                                        |
| --------------- | ------------------------------------------------------------- |
| Header-Name     | `x-api-key`                                                   |
| Geltungsbereich | Eine Organisation pro Key                                     |
| Berechtigungen  | Fehlende Berechtigungen führen auch mit gültigem Key zu `403` |

## Key erstellen

1. Öffne **Integrationen → API-Keys** im SquadVault-Dashboard (auch über den [Integrationen](/de/user-guide/integrations)-Hub erreichbar).
2. Erstelle einen Key und wähle die benötigten Berechtigungen aus.
3. Kopiere das Secret einmalig – lege es in einer Umgebungsvariablen wie `SQUADVAULT_API_KEY` ab.

<Warning>
  Behandle API-Keys wie Passwörter. Committe sie nicht in die Versionskontrolle und teile sie nicht in Discord.
</Warning>

## Beispiel

```bash theme={null}
curl -X GET "https://api.squadvault.xyz/v1/players/YOUR_ORG_ID" \
  -H "x-api-key: $SQUADVAULT_API_KEY"
```

```javascript theme={null}
const response = await fetch(
  "https://api.squadvault.xyz/v1/players/YOUR_ORG_ID",
  {
    headers: {
      "x-api-key": process.env.SQUADVAULT_API_KEY,
    },
  },
);
```

## Fehler bei der Authentifizierung

| Status | `error`         | Bedeutung                                                        |
| ------ | --------------- | ---------------------------------------------------------------- |
| 401    | `unauthorized`  | Keine gültige Session oder kein API-Key                          |
| 401    | `invalidApiKey` | Key fehlt, ist abgelaufen, widerrufen oder ungültig              |
| 403    | `forbidden`     | Key gültig, aber falsche Organisation oder fehlende Berechtigung |
| 429    | `rateLimited`   | Key hat sein Request-Rate-Limit überschritten                    |

Den gemeinsamen Aufbau des Fehler-Bodys findest du unter [Fehler](/de/api/errors).