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

# API-Übersicht

> Service-Key-API für ACU-Analysen, Gruppenverwaltung und ACU-Limits in Federal-Bereitstellungen.

<Info>
  Diese Dokumentation gilt für die Federal-Bereitstellungen von Devin. [Zurück zur Devin-Dokumentation](/de/get-started/devin-intro)
</Info>

Enterprise-Administratoren im Federal-Bereich können den ACU-Verbrauch programmgesteuert abfragen und [Gruppen](/de/federal/groups), [Modellverfügbarkeit](/de/federal/model-provisioning) sowie [ACU-Limits](/de/federal/acu-limits) über eine Service-Key-API verwalten. Ein [Python SDK](/de/federal/api/python-sdk) kapselt jeden in diesem Abschnitt beschriebenen Endpunkt.

Die Endpunkte für Gruppenverwaltung und ACU-Obergrenzen sind nur in self-hosted Federal-Bereitstellungen mit mehreren Mandanten verfügbar. Sie sind in kommerziellen Bereitstellungen nicht verfügbar. Die Analyseendpunkte (`/Analytics`, `/UserPageAnalytics` und `/CascadeAnalytics`) prüfen außerdem die Analytics-Zugriffsebene der Bereitstellung; ein Team ohne Analytics-Zugriff erhält `permission_denied`.

***

<div id="base-url">
  ## Base URL
</div>

Alle Anfragen werden als JSON-`POST`-Anfragen an den API-Server Ihres Deployments gesendet:

```
https://<your-server>/api/v1/<Method>
```

Ersetzen Sie `<your-server>` durch die API-Domain Ihrer Federal-Bereitstellung.

<div id="authentication">
  ## Authentifizierung
</div>

Jede Anfrage wird mit einem **Service-Schlüssel** authentifiziert, der im Request-Body enthalten ist:

```json theme={null}
{
  "service_key": "your_service_key_here"
}
```

Um einen Service-Schlüssel zu erstellen, melden Sie sich als Teamadministrator beim Federal Portal an und navigieren Sie zu **Settings → Service-Schlüssel**. Erstellen Sie dann einen Schlüssel mit den Berechtigungen für die Endpunkte, die Sie aufrufen möchten.

<Warning>Bewahren Sie Service-Schlüssel sicher auf. Verwenden Sie sie niemals in clientseitigem Code und committen Sie sie nicht in Repositorys.</Warning>

<div id="required-permissions">
  ### Erforderliche Berechtigungen
</div>

| Endpunkt                                                                                                                  | Erforderliche Berechtigung |
| ------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| [Legacy-Nutzungsbericht](/de/federal/api/python-sdk#per-user-usage-report) (`/UserPageAnalytics` and `/CascadeAnalytics`) | Teams Read-Only            |
| [ACU-Verbrauch](/de/federal/api/acu-consumption) (`/Analytics`)                                                           | Analytics Read             |
| [Gruppen auflisten](/de/federal/api/group-management#list-groups) (`/ListGroups`)                                         | Teams Read-Only            |
| [Gruppe abrufen](/de/federal/api/group-management#get-group) (`/GetGroup`)                                                | Teams Read-Only            |
| [Gruppe erstellen](/de/federal/api/group-management#create-group) (`/CreateGroup`)                                        | Teams Update               |
| [Gruppe aktualisieren](/de/federal/api/group-management#update-group) (`/UpdateGroup`)                                    | Teams Update               |
| [Gruppe löschen](/de/federal/api/group-management#delete-group) (`/DeleteGroup`)                                          | Teams Update               |
| [Gruppenmitglieder auflisten](/de/federal/api/group-management#list-group-members) (`/ListGroupMembers`)                  | Teams Read-Only            |
| [Gruppenmitglieder hinzufügen](/de/federal/api/group-management#add-group-members) (`/AddGroupMembers`)                   | Teams Update               |
| [Gruppenmitglieder entfernen](/de/federal/api/group-management#remove-group-members) (`/RemoveGroupMembers`)              | Teams Update               |
| [ACU-Obergrenze eines Nutzers abrufen](/de/federal/api/acu-caps#get-a-users-acu-cap) (`/GetUserAcuCap`)                   | Teams Read-Only            |
| [ACU-Obergrenze eines Nutzers aktualisieren](/de/federal/api/acu-caps#set-or-clear-a-users-acu-cap) (`/UpdateUserAcuCap`) | Teams Update               |

<div id="team-scoped-and-group-scoped-keys">
  ### Schlüssel mit Team- oder Gruppenbereich
</div>

Service-Schlüssel erhalten bei ihrer Erstellung einen Geltungsbereich:

* **Schlüssel mit Teambereich** können teamweite Daten abfragen und alle Gruppen im Team verwalten.
* **Schlüssel mit Gruppenbereich** sind auf die ihnen zugewiesene Gruppe beschränkt. Sie können die aggregierte ACU-Gesamtsumme und Nutzerzeilen der Gruppe lesen, nur diese Gruppe auflisten und lesen sowie ACU-Obergrenzen nur für aktuelle Mitglieder dieser Gruppe lesen oder aktualisieren. Sie können keine teamweiten Gesamtsummen oder Nutzerzeilen lesen, keine anderen Gruppen einsehen und keine Gruppen erstellen.

<div id="pagination">
  ## Paginierung
</div>

Gruppen, Gruppenmitglieder und ACU-Zeilen pro Nutzer werden seitenweise aufgelistet:

* `page_size` — optional; standardmäßig 100, maximal 1.000. Wenn dieser Wert weggelassen oder `0` übergeben wird, wird der Standardwert verwendet.
* `next_page_token` — wird zurückgegeben, wenn weitere Ergebnisse verfügbar sind. Übergeben Sie ihn als `page_token` in einer ansonsten identischen Anfrage (einschließlich desselben `page_size`), um die nächste Seite abzurufen.

Seitentokens sind nicht lesbar und verschlüsselt. Sie laufen nach 24 Stunden ab. Tokens für den ACU-Verbrauch sind an Endpunkt, Team, Geltungsbereich, Zeitraum, Gruppenauswahl und Seitengröße gebunden. Tokens für Gruppen- und Mitgliederlisten sind an Endpunkt, Team, Geltungsbereich und Seitengröße gebunden. Wenn ein gebundener Wert zwischen Seiten geändert wird, wird der Fehler `invalid_argument` zurückgegeben.

<div id="errors">
  ## Fehler
</div>

Fehler werden als JSON mit einem Code und einer Nachricht zurückgegeben:

```json theme={null}
{
  "code": "permission_denied",
  "message": "service key role is missing the required permission"
}
```

| Code                  | Bedeutung                                                                                                                                                                                                                                                        |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `unauthenticated`     | Der Service-Schlüssel fehlt, ist ungültig oder abgelaufen.                                                                                                                                                                                                       |
| `permission_denied`   | Der Rolle des Service-Schlüssels fehlt die erforderliche Berechtigung.                                                                                                                                                                                           |
| `invalid_argument`    | Die Anfrage ist fehlerhaft – zum Beispiel aufgrund eines ungültigen Zeitraums, einer Custom-Analytics-Abfrage mit gemischten typisierten und benutzerdefinierten Analysen, eines leeren Updates oder eines veralteten bzw. nicht übereinstimmenden Seitentokens. |
| `not_found`           | Die Ressource existiert nicht, gehört zu einem anderen Team oder liegt außerhalb des Geltungsbereichs des Service-Schlüssels. Teamübergreifende Ressourcen und Ressourcen außerhalb des Geltungsbereichs sind nicht von fehlenden Ressourcen zu unterscheiden.   |
| `failed_precondition` | Die Anfrage ist gültig, kann jedoch im aktuellen Zustand nicht abgeschlossen werden, etwa beim Festlegen einer ACU-Obergrenze für ein Team ohne ACU-Abrechnung oder beim Auswählen einer mehrdeutigen Nutzer-E-Mail-Adresse.                                     |
| `already_exists`      | Der angeforderte Gruppenname wird bereits vom Team verwendet.                                                                                                                                                                                                    |
| `internal`            | Der Dienst konnte die Anfrage nicht abschließen.                                                                                                                                                                                                                 |