API · v1 · stabil
CODEMETA OS Developer Center
Konsole öffnen
Foundation

Auth-Scopes

Codemeta OS unterscheidet drei öffentliche API-Scopes mit unterschiedlichen Auth-Mechanismen und Kontext-Anforderungen. Welcher Scope greift, hängt am URL-Präfix.

Übersicht

ScopePräfixAuthMandantenkontext
Tenant/api/v1Session-Cookie + 2FAPflicht (X-Tenant-Id)
Public/api/v1/publicToken / Slug / Share-LinkAus dem Token abgeleitet
Agent/api/v1/agentAgent-API-KeyAus dem Agent-Asset abgeleitet

Daneben gibt es zwei Sonderpfade:

  • /api/auth — Auth-Endpoints (sign-in/-out, 2FA, Session). Kein Mandant. Mehr unter Auth & Sessions.
  • /webhooks — externe Provider-Webhooks. Provider-spezifische Auth. Mehr unter Webhook-Ingress.

Tenant-Scope (/api/v1)

Der Standard-Scope für die normale Web-App. Jeder Request:

  1. Hat eine gültige Session-Cookie.
  2. Schickt X-Tenant-Id mit der UUID des Mandanten.
  3. Lizenz-Gate (Modul muss für den Tenant aktiv sein).
  4. Quota-Gate (KI-Calls, Storage etc.).
  5. Authorization-Gate (Permission + Datenscope).
curl https://os.codemeta.de/api/v1/tickets \
  -H "X-Tenant-Id: $TENANT" \
  -b cookies.txt

Mehr in den Konventionen und unter Multi-Tenancy.

Public-Scope (/api/v1/public)

Endpoints, die ohne Session erreichbar sind — typischerweise per signiertem Token oder Public-Slug. Beispiele:

  • Approval-Links für externe Genehmiger
  • Booking-Portal für Endkunden
  • Survey-/Event-Registrierung
  • Newsletter-Unsubscribe & Tracking-Pixel
  • eSign-Signing-Page mit Recipient-Token
  • Shared-Link zum sicheren Secret-Abruf
  • Status-Polling für Wartungsfenster
  • Domain-Branding-Resolution

Der Mandantenkontext wird aus dem Token / der Domain abgeleitet — X-Tenant-Id ist nicht erforderlich. Permissions gelten nicht; Zugriff regelt der Token.

Mehr unter Public Endpoints.

Agent-Scope (/api/v1/agent)

Für RMM-Agents auf Endpoint-Geräten. Authentifiziert per Agent-API-Key (generiert beim Enrollment). Mandant ergibt sich aus dem Asset, das den Key trägt.

Operationen: Telemetrie pushen, Konfiguration ziehen, Tasks bestätigen. Enrollment per QR-Code, Key oder Auto-Enroll.

Mehr unter Agent-API.

Webhook-Ingress (/webhooks & /api/v1/webhooks)

Eingehende Webhooks von externen Diensten (Stripe, INWX, Microsoft Graph, externe Telefonie- und Mail-Provider, …). Provider-spezifische Auth-Header und Signaturen.

Davon unterschieden: Outbound-Webhooks, die Codemeta OS an Subscriber schickt — siehe Webhooks (Outbound).

Mehr unter Webhook-Ingress.

Verwandt

Suche