Copera Public API Authentifizierung: Token-Typen und Scopes

Jede Public-API-Anfrage muss ein Token im Header Authorization mit dem Schema Bearer enthalten:

Authorization: Bearer <token>

Copera akzeptiert drei allgemeine Public-API-Token-Typen. Das Präfix zeigt Ihnen (und der API), welchen Typ Sie verwenden. Das Omni-Web-Widget hat zusätzlich einen separaten, quellengebundenen Server-API-Key zum Erzeugen kurzlebiger Besucher-Identity-Tokens.

Token-Typ	Präfix	Identität	Oberfläche
Personal Access Token	cp_pat_	Sie (der Benutzer, der es erstellt hat)	Volle API
Integration API Key	cp_key_	Die Integration (ein Bot)	Nur Boards + Channels
MCP-OAuth-Token	cp_oat_	Der verbundene Benutzer	Ausgestellt vom MCP-Server
Omni-Widget-Server-API-Key	cp_omni_sk_	Eine Web-Widget-Quelle	Nur Omni-Widget-Identity-Tokens erzeugen

Personal Access Token (cp_pat_)

Ein Personal Access Token authentifiziert die API als Sie. Anfragen werden Ihrem Benutzerkonto zugeschrieben und erben Ihren Zugriff im Workspace, begrenzt durch die Scopes, die Sie dem Token gewähren. PATs schalten die gesamte API-Oberfläche frei — Boards, Export, Docs, Drive, Suche, Channels, Benachrichtigungen, Workspace und Bookings — und sind die empfohlene Wahl für Skripte, CI-Pipelines und persönliche Automatisierung.

So erhalten Sie eines

1. Öffnen Sie Workspace-Einstellungen → Integrationen.
2. Wählen Sie den Tab Personal Tokens.
3. Klicken Sie auf Create new token.
4. Setzen Sie einen Namen, wählen Sie die benötigten Scopes und ein Ablaufdatum (bis zu 1 Jahr).
5. Kopieren Sie das Token sofort — es wird nur einmal angezeigt.

Eigenschaften

• Workspace-bezogen — jedes Token ist an einen Workspace gebunden.
• Wirkt als Ihre Identität — Aufrufe werden Ihnen zugeschrieben und respektieren Ihre Berechtigungen.
• Läuft ab — maximal 1 Jahr; abgelaufene Tokens liefern 401.
• Scoped — nur die von Ihnen vergebenen Scopes gelten.

Beispiel

curl https://api.copera.ai/public/v1/docs/tree \
  -H "Authorization: Bearer cp_pat_your_token_here"

Integration API Key (cp_key_)

Ein Integration API Key authentifiziert als Integration (Bot) statt als bestimmter Benutzer. Das ist die richtige Wahl, wenn Sie eine eigene Identität wollen, die unabhängig von einem Benutzer arbeitet — z. B. ein Bot, der in Channels postet oder Board-Daten liest.

hinweis

Integration API Keys decken nur Boards und Channels ab. Für Docs-, Drive-, Such-, Benachrichtigungs-, Workspace- oder Bookings-Endpunkte verwenden Sie stattdessen ein Personal Access Token.

Eigenschaften

• Bot-Identität — Anfragen werden der Integration zugeschrieben, nicht einem Benutzer.
• Boards- und Channels-Oberfläche — ausgelegt für Board- und Channel-Endpunkte.
• Erfordert expliziten Zugriff — der Integration müssen die passenden Scopes gewährt und sie als Teilnehmer der benötigten Channels oder Boards hinzugefügt werden.

Erstellen Sie eine Integration und erzeugen Sie ihren Key unter Workspace-Einstellungen → Integrationen.

MCP-OAuth-Token (cp_oat_)

MCP-OAuth-Tokens werden automatisch ausgestellt, wenn ein KI-Client über den MCP-Server mit Ihrem Workspace verbunden wird. Sie erzeugen sie nicht manuell — der OAuth-Flow stellt sie im Namen des Benutzers aus. Sie authentifizieren als der verbindende Benutzer, begrenzt auf das, was der MCP-Integration erlaubt ist.

Wenn Sie eine direkte Integration bauen, verwenden Sie ein PAT oder einen Integration API Key. Tokens vom Typ cp_oat_ gehören zum MCP-Verbindungsablauf.

Omni-Widget-Server-API-Key (cp_omni_sk_)

Ein Omni-Widget-Server-API-Key ist ein rein serverseitiges Credential, gebunden an eine Web-Widget-Quelle. Sein einziger Public-API-Zweck ist der Aufruf von POST /public/v1/omni-channel/identity-tokens, um ein fünf Minuten gültiges Identity-Token für einen angemeldeten Besucher zu erzeugen. Es ist kein PAT, kein Integration Key, kein Widget-channelKey, keine Channel-ID und keine Source-ID, und es nutzt nicht die allgemeinen access_*-Scopes unten.

Erstellen und verwalten Sie diese Keys im Panel Configure & install des Web-Widgets unter Server API keys. Ein Key wird nur einmal angezeigt. Mehrere aktive Keys werden unterstützt, damit Sie pro Umgebung einen eigenen Key verwenden und sicher rotieren können.

gefahr

Bewahren Sie jeden Key cp_omni_sk_… im Secret Store Ihres Backends auf. Senden Sie ihn niemals an einen Browser oder Mobile-Client. Ihr same-origin-Backend sollte den Anwendungsbenutzer authentifizieren, Copera mit dem Server-Key aufrufen und nur das kurzlebige identityToken an den Browser zurückgeben.

Siehe den sicheren verifizierten Identity-Flow des Omni-Web-Widgets für den vollständigen Backend- und Browser-Ablauf sowie die API-Referenz Create Omni identity token für das Endpunkt-Schema.

Scopes

Scopes steuern, welche Domänen ein Token erreichen kann. Gewähren Sie nur, was Ihre Integration braucht.

Scope	Gewährt Zugriff auf
access_boards	Boards, Tabellen, Zeilen, Zeilenkommentare, Zeilen-Markdown, Tabellenexport
access_channels	Channels, Channel-Nachrichten, Direktnachrichten
access_docs	Dokumente — lesen, schreiben, suchen, Baum
access_drive	Drive — browsen, suchen, herunterladen, hochladen, Ordner
access_notifications	Benachrichtigungen — listen, aktualisieren, löschen
access_bookings	Bookings und Booking-Typen

Hinweise zur Scope-Abdeckung:

• Workspace-Endpunkte (Info, Members, Teams) erfordern ein gültiges PAT eines internen (nicht externen) Benutzers — es gibt keinen separaten Workspace-Scope.
• Suche hat keinen einzelnen Scope. Eine Suchanfrage liefert nur die Entitätstypen, die Ihr Token lesen darf: Dokumente brauchen access_docs, Channels und Nachrichten access_channels, Drive-Einträge access_drive. Andere Typen (z. B. Todos und KI-Chats) sind mit jedem gültigen Token durchsuchbar.
• Export läuft auf Board-Tabellen und erfordert daher access_boards.

Eine Anfrage an eine Domäne, für die Ihrem Token der Scope fehlt, liefert 403 Forbidden. Siehe Fehlerbehandlung.

Sicherheits-Best-Practices

• Tokens sicher speichern — Umgebungsvariablen oder Secret Manager. Niemals hardcoden.
• Tokens nie committen — Token-Dateien in .gitignore; CI/CD-Secret-Store nutzen.
• Minimalen Scope verwenden — nur die Scopes anfordern, die die Integration braucht.
• Kurze Ablaufzeiten setzen — für PATs die kürzeste sinnvolle Lebensdauer wählen.
• Regelmäßig rotieren — Tokens periodisch ersetzen und ungenutzte löschen.
• Ein Token pro Einsatz — getrennte Tokens pro Integration oder Umgebung für gezieltes Widerrufen.
• Omni-Server-Keys nur im Backend — Browser erhalten nur das fünf Minuten gültige Identity-Token, nie den quellengebundenen Key cp_omni_sk_….