API-Keys¶
REST-Endpoints zum Verwalten der eigenen API-Keys.
GET /auth/api-keys¶
Liste aller API-Keys des authentifizierten Accounts.
Antwort:
{
"data": [
{
"id": 42,
"name": "monitoring-prometheus",
"key_prefix": "nmg_a1b2c3d4e5f6g7h8",
"scope": "read-only",
"rate_limit_per_minute": 100,
"last_used_at": "2026-05-01T08:42:13Z",
"expires_at": null,
"created_at": "2026-04-15T11:30:00Z"
}
],
"error": null,
"message": "OK"
}
Der volle Key wird nicht zurückgegeben — nur das Prefix für UI-Identifikation.
POST /auth/api-keys¶
Neuen API-Key erstellen.
curl -X POST \
-H 'X-API-Key: nmg_<existing-admin-key>' \
-H 'Content-Type: application/json' \
-d '{
"name": "ci-deployment-bot",
"scope": "domain-admin",
"rate_limit_per_minute": 60
}' \
https://mailguard.example.com:3443/api/v1/auth/api-keys
Antwort (Key-Wert wird einmalig zurückgegeben):
{
"data": {
"id": 43,
"key": "nmg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"key_prefix": "nmg_xxxxxxxxxxxxxxxx",
"name": "ci-deployment-bot",
"scope": "domain-admin",
"rate_limit_per_minute": 60,
"expires_at": null
},
"error": null,
"message": "Created"
}
Den key-Wert sofort speichern — er wird nie wieder zurückgegeben. Bei Verlust: Key revoken und neuen erstellen.
Scopes¶
| Scope | Erlaubt |
|---|---|
read-only |
Nur GET-Endpoints |
quarantine-only |
Quarantäne-Aktionen (Release, Discard) |
domain-admin |
Alle Operationen für eine spezifische Domain |
full-admin |
Alles, kein Scope-Limit |
POST /auth/api-keys/{id}/revoke¶
Key sofort ungültig machen, ohne ihn zu löschen.
curl -X POST -H 'X-API-Key: nmg_<...>' \
https://mailguard.example.com:3443/api/v1/auth/api-keys/43/revoke
Bestehende Requests mit dem revoked Key bekommen sofort 401 Unauthorized.
DELETE /auth/api-keys/{id}¶
Key komplett aus DB entfernen.
curl -X DELETE -H 'X-API-Key: nmg_<...>' \
https://mailguard.example.com:3443/api/v1/auth/api-keys/43
Unterschied zu Revoke: Delete entfernt auch das Audit-Log-Mapping. Forensisch besser ist Revoke (zeigt im Audit „Key war aktiv von … bis …").