Zum Hauptinhalt springen

API

Die API lässt Sie Exporte programmatisch auslösen — für Integrationen und eigene Workflows. Sie ist Teil der Exportelier Automation-App.

Authentifizierung​

Aufrufe werden mit einem Bearer-Token authentifiziert, das Sie in der Automation-App unter Einstellungen → REST-API-Tokens erzeugen. Jedes Token ist an genau einen Zeitplan gebunden: Die Anfrage sagt führe dies aus, nie führe diese Abfrage aus.

Das vollständige Token wird einmal angezeigt — beim Erzeugen oder beim Rotieren. Gespeichert wird nur sein Hash, es lässt sich also später nicht erneut abrufen. Kopieren Sie es in diesem Moment in Ihre Integration.

Gültigkeit und Rotation​

Jedes Token wird mit einer Gültigkeit von 30, 90, 180 oder 365 Tagen ausgegeben (Standard: 90) und funktioniert nach Ablauf nicht mehr. Eine unbegrenzte Option gibt es bewusst nicht: Diese Zugangsdaten liegen in Build-Pipelines und Integrationskonten außerhalb von Jira, wo sie niemand für Sie ablaufen lässt.

Rotieren erzeugt ein neues Secret für ein bestehendes Token und behält Name, gebundenen Zeitplan und Verlauf. Das bisherige Secret funktioniert sofort nicht mehr — es gibt kein Überlappungsfenster —, aktualisieren Sie das aufrufende System also im selben Zug. Die Rotation startet außerdem die Gültigkeitsdauer neu.

Tokens, die vor Einführung der Gültigkeit erzeugt wurden, funktionieren weiter und werden als „Kein Ablauf — dieses Token rotieren" gelistet. Rotieren Sie ein solches Token, um es unter die aktuelle Richtlinie zu bringen.

Was der Endpunkt zurückgibt​

Ein unbekanntes, widerrufenes, abgelaufenes oder vertipptes Token liefert jeweils dieselbe 401 mit {"error":"unauthorized"}. Das ist Absicht: Die Antwort darf einem Aufrufer nicht verraten, ob ein bestimmtes Token existiert.

StatusBodyBedeutung
202{"jobId":…,"status":"queued"}Der Export wurde eingereiht.
200{"jobId":…,"status":"queued"}Wiederholung einer früheren Anfrage mit demselben Idempotency-Key.
401{"error":"unauthorized"}Token unbekannt, widerrufen, abgelaufen oder Secret falsch.
403{"error":"forbidden"}Das Automation-Abonnement ist nicht aktiv.
404 / 409{"error":"schedule_not_found"} / {"error":"schedule_disabled"}Der gebundene Zeitplan fehlt oder ist pausiert.
429{"error":"rate_limited"}Rate-Limit erreicht — siehe Limits-Referenz.

Token-Aktivität prüfen​

Wenn Sie ein Token in der Liste aufklappen, sehen Sie die zuletzt ausgelösten Exporte mit ihren Job-IDs sowie die Anzahl der Versuche mit falschem Secret. Eine steigende Zahl fehlgeschlagener Versuche bei einem Token, das Sie gerade nicht nutzen, ist ein Grund zu rotieren.

Verwaltung der REST-API-Token mit Tokenname und Auswahl des zugeordneten Zeitplans. Verwaltung der REST-API-Token mit Tokenname und Auswahl des zugeordneten Zeitplans.

Typischer Ablauf​

  1. Authentifizieren.
  2. Einen Export anfordern (Kontext, Vorlage, Format).
  3. Bei großen Exporten den Job-Status abfragen.
  4. Das Ergebnis abrufen.

Rate-Limits​

Die API unterliegt Rate-Limits — siehe Limits-Referenz. Für ereignisgesteuerte Zustellung erwägen Sie Webhooks statt Polling.

Genaue Endpunkte

Endpunkt-Pfade und Request-/Response-Schemas sind im Produkt dokumentiert und werden hier ergänzt. Diese Seite beschreibt das Modell und den Ablauf.