Spedy Docs

Alle API-Anfragen erfordern Authentifizierung via Personal Access Token (PAT). PATs bieten langlebigen API-Zugriff für Skripte, CI/CD-Pipelines und Integrationen. Sie erben die Berechtigungen des Nutzers, der sie erstellt hat.

PATs erfordern ein Pro-Plan-Abonnement.

Token erstellen

Offne Einstellungen > Konto > Access Tokens im Spedy-Dashboard.
Klicke auf Token erstellen und vergib einen beschreibenden Namen (z.B. "CI Pipeline" oder "Zapier Integration").
Kopiere das Token sofort -- es wird nur einmal angezeigt und kann danach nicht mehr abgerufen werden.

Token verwenden

Fuege das Token im Authorization-Header jeder API-Anfrage ein:

curl -H "Authorization: Bearer spedy_pat_abc123def456..." \
  https://acme-corp.spedy.ai/api/v1/tickets

Das Token ist auf die Organisation des Nutzers beschraenkt, der es erstellt hat. Alle Anfragen werden mit den Berechtigungen dieses Nutzers ausgefuehrt.

Token-Format und Sicherheit

Tokens beginnen mit dem Praefix spedy_pat_ zur einfachen Identifikation.
Behandle Tokens wie Passwoerter -- committe sie niemals in die Versionskontrolle und teile sie nicht im Klartext.
Verwende Umgebungsvariablen oder einen Secrets-Manager, um Tokens in CI/CD-Pipelines zu speichern.
Widerrufe Tokens, die du nicht mehr benoetigst.

Token-Verwaltungs-Endpunkte

Tokens auflisten

GET /api/v1/me/tokens

Gibt alle aktiven Tokens des aktuellen Nutzers zurueck.

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 vollstaendige Token-Wert wird nur einmal in der Antwort zurueckgegeben -- speichere ihn sicher.

Request Body

Feld	Typ	Pflicht	Beschreibung
name	string	Ja	Ein beschreibender Name fuer 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 rueckgaengig gemacht werden. Gibt 204 No Content bei Erfolg zurueck.

Agenten-Tokens und Scopes pro Token

Ein Agenten-User hat gar kein Login und authentifiziert sich ausschliesslich mit Tokens. Seine Tokens werden ueber die Agenten-Endpunkte von einem Admin oder vom Eigentuemer des Agenten erzeugt, nie vom Agenten selbst. Agenten-User brauchen Pro; MCP selbst gibt es auf jedem Plan, ein Loop kann also auch unter dem Token einer Person laufen — nur eben ohne eigene Identitaet.

Persoenliche und Agenten-Tokens akzeptieren beim Erzeugen dieselben Einschraenkungen:

Option	Typ	Wirkung
`allowedBoardIds`	string[]	Begrenzt das Token auf diese Projekte, unabhaengig von den Mitgliedschaften des Users (max. 100). Leer oder weggelassen = alle erreichbaren Projekte
`readOnly`	boolean	Nur Lese-Tools und `GET`-Requests. Das Token darf schauen, nicht aendern
`denyDelete`	boolean	Sperrt jede Lösch-Faehigkeit und jeden `DELETE`-Request. Standard `true` fuer Agenten-Tokens, `false` fuer persoenliche
`clientLabel`	string \| null	Freitext fuer den Client, der das Token nutzt ("claude-code loop auf ci-1"). Er erscheint als Client an Kommentaren, Zeiteintraegen und Statuswechseln — und schlaegt das, was der MCP-Client ueber sich selbst behauptet
`expiresInDays`	number \| null	Laufzeit in Tagen (1–3650). Weglassen oder `null` = laeuft nie ab

Fail-closed

Scopes verengen, sie erweitern nie. Ein Token kann immer nur eine Teilmenge dessen, was sein User darf — und eine Einschraenkung, die sich nicht auswerten laesst, gilt als „nicht erlaubt":

Ein auf zwei Projekte begrenztes Token erreicht kein drittes, auch wenn der User dort Mitglied ist.
Ein Request, dessen Ziel-Board sich nicht aufloesen laesst, wird abgelehnt statt durchgewunken.
Agent deaktivieren, Token widerrufen oder Agent loeschen schneidet jeden Loop sofort ab.

Fehlercodes

Ein abgelehnter Request antwortet mit 403 und einem stabilen Code, damit ein Loop ein Scope-Problem von einem Berechtigungsproblem unterscheiden kann:

Code	Bedeutung
`PAT_READ_ONLY`	Das Token ist nur lesend, der Request war ein Schreibzugriff
`PAT_DENY_DELETE`	Das Token darf nicht loeschen, der Request war destruktiv. Eine enge Ausnahme: Den eigenen Ticket-Claim freizugeben ist immer erlaubt; nur der Claim eines fremden Akteurs loest diesen Code aus
`PAT_BOARD_NOT_ALLOWED`	Das Ziel-Projekt steht nicht in `allowedBoardIds` des Tokens

Die MCP-Oberflaeche wirft dieselben Codes, dieselbe Loop-Logik funktioniert also ueber beide Wege.

Was zusaetzlich fuer Agenten gilt

Fuer einen Agenten-User gilt ueber REST genau dasselbe wie ueber MCP — es gibt keine guenstigere Tuer:

Status-Freigabe-Policy. Ein Wechsel in einen Status, den die Organisation Menschen vorbehaelt, wird mit 403 AGENT_APPROVAL_REQUIRED abgelehnt; stattdessen entsteht ein Vorschlag, den ein Mensch annimmt.
Zeitfaktor und Wochenlimit. Von einem Agenten erfasste Zeit landet als Entwurf mit PENDING-Freigabe, skaliert mit seinem MCP-Zeitfaktor; ist das Wochenlimit erreicht, scheitert der Timer-Start mit AGENT_HOURS_CAP_REACHED.
Claim-Obergrenze. Ein Agent darf nur eine begrenzte Zahl Ticket-Claims gleichzeitig halten (Standard 3) — darueber 403 CLAIM_LIMIT_REACHED.

OAuth 2.0

Fuer externe Anwendungen wie KI-Tools, IDE-Erweiterungen und MCP-faehige Clients unterstuetzt Spedy auch OAuth 2.0 mit PKCE. OAuth ist auf allen Plaenen verfuegbar (einschliesslich Starter und Trial) und ist die empfohlene Authentifizierungsmethode fuer Drittanbieter-Integrationen.

Siehe die OAuth-2.0-Seite fuer die vollstaendige Referenz.

Authentifizierung

Inhaltsverzeichnis