Authentifizierung

Wie Authentifizierung an der go~mus-API funktioniert - Bearer-Tokens, Kontextsensitivität, foreign_id-Pattern, Best Practices.

go~mus authentifiziert API-Aufrufe über Bearer-Tokens. Das ist Standard-OAuth-2.0-Pattern. Spezial: Tokens sind kontextsensitiv. Die Antwort variiert je nach Token.

Header-Format

In jedem Request:

Authorization: Bearer <token>

Beispiel:

curl -H "Authorization: Bearer abc123def456..." \
  https://demo.gomus.de/api/v4/whoami

Token-Typen

Drei Klassen von Tokens, alle gleich aufgebaut, unterschiedlich autorisiert:

  • Public: lesend, keine Auth-Pflicht für die meisten Endpunkte. Wenn Auth genutzt, sind manche Felder oder Filter zusätzlich verfügbar.
  • User: für Backend-User. Sieht alles im Rahmen der zugewiesenen Rechte und Museen.
  • Reseller: für Vertriebspartner. Liest nur die für sie freigegebenen Tickets/Events. Schreibt Orders, Reservations. Mit Rate-Limit.

Welcher Token-Typ für deinen Use-Case passt, klärt go~mus-Support beim Setup.

Kontextsensitivität in Aktion

Gleicher Endpoint, drei Token, drei Antworten:

# Public-Aufruf (kein Token)
curl https://demo.gomus.de/api/v4/tickets
# → öffentliche Liste, ggf. eingeschränkt

# Mit User-Token
curl -H "Authorization: Bearer USER_TOKEN" \
  https://demo.gomus.de/api/v4/tickets
# → vollständiges Backend-Inventar

# Mit Reseller-A-Token
curl -H "Authorization: Bearer RESELLER_A_TOKEN" \
  https://demo.gomus.de/api/v4/tickets
# → nur die für Reseller A freigegebenen Tickets

Heißt für deine Implementierung: schreibe nicht hartkodierte Annahmen über Felder oder Anzahl. Logge unbekannte Felder, statt zu crashen.

Token-Test

Vor jeder Integration den Token mit whoami validieren:

curl -H "Authorization: Bearer DEIN_TOKEN" \
  https://demo.gomus.de/api/v4/whoami

Antwort:

{
  "access": "user",
  "museums": []
}

access ist public, user oder reseller. museums: [] heißt: alle Museen der Instanz erreichbar. Konkrete IDs schränken ein.

foreign_id-Pattern

Wenn dein System eine eigene Customer-ID hat, hänge sie als foreign_id an. Beim nächsten Update referenzierst du via foreign_id statt go~mus-ID:

# Ersterstellung mit foreign_id
curl -X POST -H "Authorization: Bearer DEIN_TOKEN" \
  -H "Content-Type: application/json" \
  https://demo.gomus.de/api/v4/customers \
  -d '{
    "name": "Max",
    "surname": "Mustermann",
    "email": "max@example.com",
    "foreign_id": "crm-customer-9f8a7b6c5d4e3f21"
  }'

# Update via foreign_id (PUT mit foreign_id-Lookup)
curl -X PUT -H "Authorization: Bearer DEIN_TOKEN" \
  -H "Content-Type: application/json" \
  https://demo.gomus.de/api/v4/customers \
  -d '{
    "foreign_id": "crm-customer-9f8a7b6c5d4e3f21",
    "phone": "+49 30 1234567"
  }'

Vorteil: keine Mapping-Tabelle bei dir. Empfehlung: 16+ Zufallszeichen oder UUID, damit die ID kollisionsfrei bleibt.

Best Practices

Tokens niemals clientseitig. Kein Browser-JS, kein Mobile-App-Bundle. Tokens auf eurem Server halten und API-Calls proxen.

Tokens nicht teilen. Pro Partner ein Token. Wenn ein Token kompromittiert wird, ist der Schaden eingrenzbar.

Tokens rotieren. Bei Personalwechsel oder Verdacht auf Leak. Über go~mus-Support oder Backend, je nach Setup.

Rate-Limits respektieren. Reseller-Tokens haben Limits. Wenn du drüber kommt, kommt 429. Implementiert exponential backoff.

Caching ja, Live-Traffic nein. Stammdaten täglich cachen. Verfügbarkeiten live. Direkt-Live-Traffic ohne Cache ist ein No-Go für Produktion.

Logging. Alle deine API-Calls mit Timestamp, Endpoint, Status, Response-Time loggen. Bei Support-Tickets brauchst du das.

Sicherheit

Bei Verdacht auf Token-Leak: Token sofort widerrufen. Mail an support@giantmonkey.de mit Betreff „Security“.

Schwachstellen, die in der API gefunden werden, bitte verantwortlich offenlegen. Siehe security.txt.

Was als Nächstes

  • Quickstart: erster Aufruf in fünf Minuten.
  • Konzepte: weitere Vokabeln, die du brauchst wirst.
  • API-Referenz: vollständige Spec auf eurer Instanz unter https://<instanz>.gomus.<tld>/api-docs.