Wie Everyn-API-Clients sich authentifizieren, Organisationen auswählen und Scopes verwenden.

Everyn-Produkt-API-Aufrufe nutzen organisationsgebundene API Keys. Ein Maschinen-Key wählt genau eine Organisation aus, deshalb leiten Produktrouten den Tenant-Kontext aus dem Bearer Credential ab und vertrauen keinen vom Client gesetzten Organisations-IDs.

Authentifizierungsmodell

Nutze den Standard-Bearer-Header für Maschinen-/API-Key-Aufrufe:

Authorization: Bearer sk-everyn-...

Produkt-API-Keys sind Maschinen-Principals. Sie können die Produktbereiche aufrufen, die von den Scopes unten abgedeckt werden, aber keine Organisationen, Mitglieder, Einladungen, Audit Events oder API Keys verwalten.

Jobs gehören verifizierten Menschen. Erstellen, Bearbeiten und Forken erfolgen über eine authentifizierte Browser Session oder Inbound MCP nach Human-OAuth-Consent. Ein Eigentümer darf seinen Job bearbeiten; ein anderes Mitglied mit Schreibberechtigung darf ihn forken. Ein Maschinen-Key kann einen vorhandenen Job lesen und bei entsprechender Berechtigung ausführen, aber keinen Job erstellen, bearbeiten, forken, entwerfen oder freigeben. Der alte Scope job_specs:write verleiht keine menschliche Autorisierung zum Erstellen von Jobs. Nutze weder Browser-Cookies noch persönliche Tokens in einer Maschinenintegration.

Organization-Admin-Routen verlangen einen Human Principal, der auf zwei Wegen vorgelegt werden kann: als Browser Session oder als Bearer Credential, das kein API Key ist. Die Fehlerfälle unterscheiden sich — eine abgelaufene Browser Session liefert session_expired, ein abgelehntes Bearer Credential dagegen authentication_failed.

Implementierte Maschinen-Key-Scopes:

Scope	Verwendung
`datasets:read` / `datasets:write`	Dataset-Reads und Dataset-Upload-Intake.
`job_specs:read`	Model-Catalog-Reads und Reads vorhandener Jobs.
`job_specs:write`	Historischer Maschinen-Scope; autorisiert weder Job-Erstellung noch Bearbeitung, Forks, Entwürfe oder Freigaben.
`runs:read` / `runs:write`	Run-Erstellung, Start, Cancel, Retry, Inspektion, Rows, Outputs und Failures.
`exports:read` / `exports:write`	Export-Erstellung, Polling, Listing und Download.
`alert_rules:read` / `alert_rules:write`	Alert Rules und Alert-Delivery-Inspektion.
`webhooks:read` / `webhooks:write`	Webhook Endpoints, Secret Rotation, Tests und Delivery-Inspektion.

Häufige Auth-Ergebnisse:

Status	Bedeutung	Nächster Schritt
`401 authentication_failed`	Fehlendes, fehlerhaftes, unbekanntes, widerrufenes oder abgelaufenes Credential.	Bearer Credential ersetzen.
`403 authorization_failed`	Credential ist gültig, aber Scope oder Rolle fehlt.	Credential mit erforderlichem Scope oder Admin-Rolle nutzen.
`403 human_authoring_required`	Ein Maschinen-Credential hat versucht, einen Job zu erstellen oder zu bearbeiten.	Verifizierten Menschen über Browser Session oder Inbound MCP mit OAuth-Consent autorisieren lassen.
`403 job_owner_required`	Ein Mensch hat versucht, den Job einer anderen Person zu bearbeiten.	Eigentümer bearbeiten lassen oder den Job mit aktueller Workspace-Schreibberechtigung forken.
`404 not_found`	Ressource existiert nicht für die authentifizierte Organisation.	Prüfen, ob die ID zur selben Organisation gehört.

Nutze API-Fehler für Recovery-Muster und die generierte Referenz für Endpoint-spezifische Auth-Anforderungen.