Authentification de la Copera Public API : types de tokens et scopes

Chaque requête de la Public API doit inclure un token dans l'en-tête Authorization avec le schéma Bearer :

Authorization: Bearer <token>

Copera accepte trois types de tokens généraux de la Public API. Le préfixe vous indique (et indique à l'API) lequel vous utilisez. Le widget web Omni a aussi une clé d'API serveur séparée, liée à la source, pour créer des tokens d'identité de visiteurs de courte durée.

Type de token	Préfixe	Identité	Surface
Personal Access Token	cp_pat_	Vous (l'utilisateur qui l'a créé)	API complète
Integration API Key	cp_key_	L'intégration (un bot)	Boards + Channels uniquement
Token MCP OAuth	cp_oat_	L'utilisateur connecté	Émis par le serveur MCP
Clé d'API serveur du widget Omni	cp_omni_sk_	Une source de widget web	Créer des tokens d'identité du widget Omni uniquement

Personal Access Token (cp_pat_)

Un Personal Access Token authentifie l'API en tant que vous. Les requêtes sont attribuées à votre compte utilisateur et héritent de votre accès dans le workspace, sous le contrôle des scopes que vous accordez au token. Les PAT débloquent la surface API complète — boards, export, docs, drive, search, channels, notifications, workspace et bookings — et sont le choix recommandé pour les scripts, pipelines CI et automatisations personnelles.

Comment en obtenir un

1. Ouvrez Workspace Settings → Integrations.
2. Sélectionnez l'onglet Personal Tokens.
3. Cliquez sur Create new token.
4. Définissez un nom, choisissez les scopes dont il a besoin, et définissez une date d'expiration (jusqu'à 1 an).
5. Copiez le token immédiatement — il n'est affiché qu'une seule fois.

Caractéristiques

• Scopé au workspace — chaque token est lié à un workspace.
• Agit comme votre identité — les appels vous sont attribués et respectent vos permissions.
• Expire — jusqu'à un maximum de 1 an ; les tokens expirés renvoient 401.
• Scopé — seuls les scopes que vous accordez sont honorés.

Exemple

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

Integration API Key (cp_key_)

Une Integration API Key s'authentifie comme une intégration (un bot) plutôt que comme un utilisateur spécifique. C'est le bon choix lorsque vous voulez une identité séparée qui opère indépendamment de tout utilisateur — par exemple un bot qui poste dans des channels ou lit des données de board.

note

Les Integration API Keys couvrent uniquement boards et channels. Pour appeler les endpoints docs, drive, search, notifications, workspace ou bookings, utilisez plutôt un Personal Access Token.

Caractéristiques

• Identité bot — les requêtes sont attribuées à l'intégration, pas à un utilisateur.
• Surface boards + channels — conçue pour les endpoints board et channel.
• Exige un accès explicite — l'intégration doit se voir accorder les scopes pertinents et être ajoutée comme participante des channels ou boards spécifiques qu'elle doit atteindre.

Créez une intégration et générez sa clé depuis Workspace Settings → Integrations.

Token MCP OAuth (cp_oat_)

Les tokens MCP OAuth sont émis automatiquement lorsqu'un client IA se connecte à votre workspace via le serveur MCP. Vous ne les créez pas à la main — le flux OAuth les crée au nom de l'utilisateur. Ils s'authentifient comme l'utilisateur qui se connecte, scopés à ce que l'intégration MCP est autorisée à faire.

Si vous construisez une intégration directe, utilisez un PAT ou une Integration API Key. Les tokens cp_oat_ font partie du flux de connexion MCP.

Clé d'API serveur du widget Omni (cp_omni_sk_)

Une clé d'API serveur du widget Omni est un identifiant backend uniquement, lié à une source de widget web. Son seul usage Public API est d'appeler POST /public/v1/omni-channel/identity-tokens et de créer un token d'identité de cinq minutes pour un visiteur connecté. Ce n'est pas un PAT, une clé d'intégration, un channelKey de widget, un ID de channel ou un ID de source, et elle n'utilise pas les scopes généraux access_* ci-dessous.

Créez et gérez ces clés depuis le panneau Configure & install du widget web sous Server API keys. Une clé n'est affichée qu'une seule fois. Plusieurs clés actives sont prises en charge afin d'utiliser une clé distincte par environnement et de faire tourner en toute sécurité.

danger

Conservez chaque clé cp_omni_sk_… dans le magasin de secrets de votre backend. Ne l'envoyez jamais à un navigateur ou un client mobile. Votre backend same-origin doit authentifier l'utilisateur de l'application, appeler Copera avec la clé serveur, et renvoyer uniquement le identityToken de courte durée au navigateur.

Voir le flux d'identité vérifiée sécurisée du widget web Omni pour le flux backend et navigateur complet, et la référence API Create Omni identity token pour le schéma de l'endpoint.

Scopes

Les scopes contrôlent quels domaines un token peut atteindre. N'accordez que ce dont votre intégration a besoin.

Scope	Accorde l'accès à
access_boards	Boards, tables, lignes, commentaires de ligne, markdown de ligne, export de table
access_channels	Channels, messages de channel, messages directs
access_docs	Documents — lecture, écriture, search, tree
access_drive	Drive — parcourir, search, download, upload, dossiers
access_notifications	Notifications — list, update, delete
access_bookings	Bookings et types de booking

Notes sur la couverture des scopes :

• Les endpoints Workspace (info, members, teams) exigent un PAT valide pour un utilisateur interne (non externe) — il n'y a pas de scope workspace séparé.
• Search n'a pas de scope unique. Une requête de search ne renvoie que les types d'entités que votre token est autorisé à lire : les documents exigent access_docs, les channels et messages exigent access_channels, les éléments du drive exigent access_drive. Les autres types (comme todos et chats IA) sont consultables avec tout token valide.
• Export s'exécute sur les tables de board, donc il exige access_boards.

Une requête vers un domaine pour lequel votre token n'a pas le scope renvoie 403 Forbidden. Voir Gestion des erreurs.

Bonnes pratiques de sécurité

• Stockez les tokens de façon sécurisée — utilisez des variables d'environnement ou un gestionnaire de secrets. Ne les codez jamais en dur.
• Ne versionnez jamais de tokens — ajoutez les fichiers de tokens au .gitignore ; utilisez le magasin de secrets de votre CI/CD.
• Utilisez le scope minimum — ne demandez que les scopes dont l'intégration a besoin.
• Définissez des expirations courtes — choisissez la durée de vie la plus courte praticable pour les PAT.
• Faites tourner régulièrement — remplacez les tokens périodiquement et supprimez ceux qui ne sont plus utilisés.
• Un token par usage — des tokens distincts par intégration ou environnement pour pouvoir révoquer de façon ciblée.
• Gardez les clés serveur Omni côté backend uniquement — les navigateurs ne reçoivent que le token d'identité de cinq minutes, jamais la clé cp_omni_sk_… liée à la source.