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

# Berechtigungen

> Erforderliche API-Key-Berechtigungen für jeden Endpunkt der Public API.

Jeder Organisations-API-Key trägt einen Satz von Berechtigungen. Endpunkte verlangen eine passende Berechtigung. Ein gültiger Key mit den falschen Berechtigungen führt zu `403`.

Dashboard-Session-Routen (Organisationseinstellungen, Discord, Billing, Audit) stehen **nicht** in dieser Tabelle. Sie brauchen eine Inhaber- oder Admin-Mitgliedschaft und lehnen API-Keys ab. Organisations-Datenexport, Inhaber-Transfer und Organisations-Löschung sind **nur für die Inhaber-Session**.

Die Pfade unten sind relativ zur Public-API-Basis-URL `https://api.squadvault.xyz/v1`.

## Berechtigungsübersicht

### Teams

| Endpunkt                               | Berechtigung  |
| -------------------------------------- | ------------- |
| `GET /teams/{organizationId}`          | `team:read`   |
| `GET /teams/{organizationId}/{teamId}` | `team:read`   |
| `POST /teams`                          | `team:create` |
| `PATCH /teams/{teamId}`                | `team:update` |
| `DELETE /teams/{teamId}`               | `team:delete` |

### Spieler

| Endpunkt                                   | Berechtigung    |
| ------------------------------------------ | --------------- |
| `GET /players/{organizationId}`            | `player:read`   |
| `GET /players/{organizationId}/{playerId}` | `player:read`   |
| `POST /players`                            | `player:create` |
| `PATCH /players/{playerId}`                | `player:update` |
| `DELETE /players/{playerId}`               | `player:delete` |

### Dokumente

| Endpunkt                               | Berechtigung      |
| -------------------------------------- | ----------------- |
| `GET /documents/{organizationId}`      | `document:read`   |
| `GET /documents/{documentId}/download` | `document:read`   |
| `POST /documents`                      | `document:create` |
| `PATCH /documents/{documentId}`        | `document:update` |
| `DELETE /documents/{documentId}`       | `document:delete` |

### Tryout-Bewerbungen

| Endpunkt                                                      | Berechtigung                        |
| ------------------------------------------------------------- | ----------------------------------- |
| `GET /tryout-applications`                                    | `tryout:read`                       |
| `GET /tryout-applications/{applicationId}`                    | `tryout:read`                       |
| `PATCH /tryout-applications/{applicationId}`                  | `tryout:update`                     |
| `POST /tryout-applications/{applicationId}/convert-to-player` | `tryout:update` und `player:create` |

Tryout-List und -Get verlangen `organizationId` als Query-Parameter. Tryout-Update und -Convert verlangen `organizationId` im JSON-Body. API-Keys brauchen `tryout:update` für Statusänderungen; Convert braucht zusätzlich `player:create`.

### Uploads

| Endpunkt                      | Berechtigung      |
| ----------------------------- | ----------------- |
| `POST /uploads/document-file` | `document:create` |

<Note>
  Beim Anfordern einer Upload-URL für ein Dokument wird `document:create` auf der Organisation geprüft, weil der Upload dazu dient, danach ein Dokument zu erstellen.
</Note>

## Least Privilege

Vergib nur die Berechtigungen, die deine Integration wirklich braucht. Für einen rein lesenden Bot aktiviere `team:read`, `player:read` und `document:read`. Ergänze `tryout:read`, wenn die Integration Bewerbungen auflisten oder einsehen soll, und `tryout:update` für Status- oder Notiz-Änderungen. Um eine Bewerbung auf den Kader zu setzen, vergib zusätzlich `player:create`. Für Dokumenten-Automatisierung ergänze `document:create`, `document:update` und `document:delete` nach Bedarf.