Spedy Docs

Einloggen, Tokens erneuern und Personal Access Tokens für den API-Zugriff verwalten.

Alle API-Anfragen erfordern Authentifizierung. Spedy unterstützt zwei Methoden: kurzlebige JWT-Tokens, die über den Login erhalten werden, und langlebige Personal Access Tokens für Skripte und Integrationen.

POST /api/v1/auth/login

Authentifiziere dich mit E-Mail und Passwort, um ein Access-Token zu erhalten.

Rate-Limit: 5 Anfragen pro Minute pro IP.

Request Body

Feld	Typ	Pflicht	Beschreibung
email	string	Ja	E-Mail-Adresse des Nutzers
password	string	Ja	Passwort (mind. 8 Zeichen)
organizationSlug	string	Nein	Organisations-Slug (wenn der Nutzer mehreren Orgs angehört)

Beispiel-Request

{
  "email": "[email protected]",
  "password": "MySecureP@ss1"
}

Beispiel-Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "usr_abc123",
    "email": "[email protected]",
    "name": "Alex",
    "role": "ADMIN"
  },
  "organizationSlug": "acme-corp"
}

Die Antwort setzt außerdem ein spedy-refresh HTTP-only Cookie, das zum Erneuern des Tokens verwendet wird.

Token erneuern

POST /api/v1/auth/refresh

Erhalte ein neues Access-Token über das Refresh-Cookie. Rufe diesen Endpunkt auf, wenn dein JWT abläuft, anstatt dich erneut einzuloggen.

Rate-Limit: 30 Anfragen pro Minute pro IP.

Headers

Header	Pflicht	Beschreibung
x-org-slug	Ja	Organisations-Slug
Cookie	Ja	Muss das `spedy-refresh`-Cookie vom Login enthalten

Beispiel-Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "usr_abc123",
    "email": "[email protected]",
    "name": "Alex",
    "role": "ADMIN"
  },
  "organizationSlug": "acme-corp"
}

Logout

POST /api/v1/auth/logout

Aktuelle Sitzung ungültig machen und das Refresh-Cookie löschen.

Beispiel-Response

{
  "success": true
}

Passwort vergessen

POST /api/v1/auth/forgot-password

Fordere eine E-Mail zum Zurücksetzen des Passworts an. Gibt immer Erfolg zurück, um E-Mail-Enumeration zu verhindern.

Rate-Limit: 3 Anfragen pro 15 Minuten pro IP.

Request Body

Feld	Typ	Pflicht	Beschreibung
email	string	Ja	E-Mail-Adresse des Kontos

Passwort zurücksetzen

POST /api/v1/auth/reset-password

Setze ein neues Passwort mit dem Reset-Token aus der E-Mail.

Rate-Limit: 5 Anfragen pro 15 Minuten pro IP.

Request Body

Feld	Typ	Pflicht	Beschreibung
token	string	Ja	Reset-Token aus dem E-Mail-Link
password	string	Ja	Neues Passwort (mind. 8 Zeichen, muss Groß-, Kleinbuchstaben, Zahl und Sonderzeichen enthalten)

Personal Access Tokens

Personal Access Tokens (PATs) bieten langlebigen API-Zugriff für Skripte, CI/CD-Pipelines und Automatisierungen. Sie erben die Berechtigungen des Nutzers, der sie erstellt hat.

PATs erfordern ein Pro-Plan-Abonnement.

Tokens auflisten

GET /api/v1/me/tokens

Gibt alle aktiven Tokens des aktuellen Nutzers zurück.

Beispiel-Response

{
  "tokens": [
    {
      "id": "tok_abc123",
      "name": "CI Pipeline",
      "lastUsedAt": "2025-03-15T10:30:00Z",
      "createdAt": "2025-01-10T08:00:00Z"
    }
  ]
}

Token erstellen

POST /api/v1/me/tokens

Erstelle ein neues Personal Access Token. Der vollständige Token-Wert wird nur einmal in der Antwort zurückgegeben -- speichere ihn sicher.

Request Body

Feld	Typ	Pflicht	Beschreibung
name	string	Ja	Ein beschreibender Name für das Token

Beispiel-Request

{
  "name": "CI Pipeline"
}

Beispiel-Response

{
  "id": "tok_abc123",
  "name": "CI Pipeline",
  "token": "spedy_pat_abc123def456...",
  "createdAt": "2025-03-20T14:00:00Z"
}

Token abrufen

GET /api/v1/me/tokens/{tokenId}

Details eines bestimmten Tokens abrufen (ohne den geheimen Wert).

Token widerrufen

DELETE /api/v1/me/tokens/{tokenId}

Ein Token dauerhaft widerrufen. Diese Aktion kann nicht rückgängig gemacht werden. Gibt 204 No Content bei Erfolg zurück.

Authentifizierung

Inhaltsverzeichnis