Authentifizierung

Die Hochzeitshelfer API verwendet Personal Access Tokens (persönliche Zugriffsschlüssel) zur Authentifizierung. Tokens werden über die Web-Oberfläche erstellt und bei jedem API-Aufruf als Bearer-Token mitgeschickt.

Token erstellen

1. Melde dich bei Hochzeitshelfer.app an
2. Navigiere zu Einstellungen → API-Tokens
3. Vergib einen Namen für den Token (z. B. „Meine Integration")
4. Wähle die gewünschten Berechtigungen aus
5. Klicke auf Token erstellen

Wichtig

Der Token wird dir nur einmal im Klartext angezeigt. Kopiere ihn sofort und bewahre ihn sicher auf. Er kann nachträglich nicht erneut abgerufen werden.

Berechtigungen (Abilities)

Jeder Token kann mit feingranularen Berechtigungen ausgestattet werden:

Berechtigung	Beschreibung
guests:read	Gästedaten lesen und auflisten
guests:write	Gäste erstellen, bearbeiten und löschen

Du kannst einem Token beide Berechtigungen zuweisen oder nur Lesezugriff gewähren, wenn du z. B. nur Daten exportieren möchtest.

Token verwenden

Sende den Token im Authorization-Header als Bearer-Token mit:

Authorization: Bearer DEIN_API_TOKEN

Beispiel mit cURL

curl -X GET https://hochzeitshelfer.app/api/v1/guests \
  -H "Authorization: Bearer 1|a3bC4dE5fG6hI7jK8lM9nO0pQ1rS2tU3vW4xY5z" \
  -H "Accept: application/json"

Beispiel mit JavaScript (fetch)

const response = await fetch('https://hochzeitshelfer.app/api/v1/guests', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer DEIN_API_TOKEN',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);

Beispiel mit Python (requests)

import requests

headers = {
    'Authorization': 'Bearer DEIN_API_TOKEN',
    'Accept': 'application/json',
}

response = requests.get(
    'https://hochzeitshelfer.app/api/v1/guests',
    headers=headers,
)

data = response.json()
print(data)

Beispiel mit PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client();

$response = $client->get('https://hochzeitshelfer.app/api/v1/guests', [
    'headers' => [
        'Authorization' => 'Bearer DEIN_API_TOKEN',
        'Accept' => 'application/json',
    ],
]);

$data = json_decode($response->getBody(), true);

Fehlende oder ungültige Tokens

Wenn kein Token oder ein ungültiger Token gesendet wird, antwortet die API mit:

Status: 401 Unauthorized

{
  "message": "Unauthenticated."
}

Fehlende Berechtigung

Wenn der Token nicht die nötige Berechtigung für den Endpunkt hat (z. B. guests:write für eine POST-Anfrage), antwortet die API mit:

Status: 403 Forbidden

{
  "message": "Unauthorized"
}

Token widerrufen

Du kannst einen Token jederzeit in den Einstellungen → API-Tokens widerrufen (löschen). Der Token ist danach sofort ungültig und kann nicht wiederhergestellt werden.

Sicherheitshinweise

• Tokens niemals im Frontend-Code (z. B. JavaScript im Browser) verwenden — nutze sie nur serverseitig
• Tokens nicht in Versionskontrolle (z. B. Git) einchecken
• Verwende Umgebungsvariablen oder einen Secrets Manager für die Aufbewahrung
• Vergib nur die minimal nötigen Berechtigungen für jeden Token
• Widerrufe nicht mehr benötigte Tokens umgehend