# API-Tokens

> Tokens für CI-Pipelines, Skripte und KI-Agenten anlegen – mit genau den Rechten, die sie brauchen.

REST-API, CLI und MCP-Server melden sich mit einem **API-Token** an. Tokens verwaltest du in der Seitenleiste unter
**API & Tokens** (nur für Workspace-Inhaber und -Admins sichtbar).

## Token erstellen

:::steps
### Formular ausfüllen

Unter **Neuer Token**:

- **Name** – wofür der Token ist, z. B. „GitHub Actions“.
- **Rechte** – siehe Tabelle unten.
- **Bereiche (leer = alle)** – den Token optional auf einzelne Bereiche beschränken.
- **Gültigkeit** – *Unbegrenzt*, *30 Tage*, *90 Tage* oder *1 Jahr*.

### Token erstellen und kopieren

Nach **Token erstellen** zeigt Docsello den Token (beginnt mit `dsl_`) **nur ein einziges Mal** an. Kopiere ihn
sofort an einen sicheren Ort, z. B. in die Secrets deiner CI.
:::

## Rechte

| Rechte | Darf |
|---|---|
| **Nur lesen** | Bereiche und Seiten lesen, suchen |
| **Bearbeiten & veröffentlichen** | Seiten anlegen, ändern, veröffentlichen und löschen, Bereiche anlegen, Medien hochladen, Screenshots definieren und neu aufnehmen. In Bereichen mit Review-Pflicht nicht veröffentlichen |
| **Bearbeiten, prüfen & veröffentlichen** | Wie oben, zusätzlich in Bereichen mit Review-Pflicht veröffentlichen |
| **Admin (alles)** | Alles, auch Bereichseinstellungen wie Sichtbarkeit und Zugriff |

Für eine Docs-Pipeline (z. B. [Docs aus Git](doc:docs-aus-git)) genügt **Bearbeiten & veröffentlichen**: Damit
darf der Token neue Bereiche anlegen und Name, Beschreibung und Symbol bestehender Bereiche anpassen. Die
Sichtbarkeit eines bestehenden Bereichs ändern nur Tokens mit *Admin (alles)* – oder du stellst sie in der Verwaltung
ein.

Jeder Aufruf wird gegen dieselben Berechtigungen geprüft wie in der Verwaltung, und jede Änderung landet mit „API“ als
Urheber im Protokoll des Workspaces.

## Verwenden

Den Token schickst du im Header `Authorization` mit:

```bash
curl "$DOCSELLO_URL/api/v1/me" -H "Authorization: Bearer $DOCSELLO_TOKEN"
```

Die [CLI](doc:cli) liest ihn aus der Umgebungsvariable `DOCSELLO_TOKEN`.

## Übersicht und Widerruf

Unter **Aktive Tokens** siehst du Name, Rechte, Bereiche, wann der Token zuletzt genutzt wurde und wann er abläuft.
**Widerrufen** sperrt einen Token sofort.

:::warning
Behandle Tokens wie Passwörter: nie ins Repository einchecken, nie in URLs schreiben. Läuft ein Token in fremde Hände,
widerrufe ihn und erstelle einen neuen.
:::