Authentification

Chaque requête porte une clé d’API de votre organisation. La clé détermine les données de quelle organisation vous lisez, et les opérations que vous pouvez appeler.

L’en-tête

Envoyez la clé dans l’en-tête Authorization, exactement ainsi :

Authorization: Bearer mcf_your_key

Bearer avec un B majuscule, une espace, puis la clé : rien avant, rien après. L’API n’accepte la clé nulle part ailleurs. Une clé placée dans les paramètres de l’URL ou dans un autre en-tête est refusée.

Les clés sont faites pour les serveurs. N’en livrez jamais dans une page web ou une application mobile : l’API ne répond à aucune requête de navigateur (CORS), et quiconque lit la clé peut s’en servir.

Créer des clés

Un administrateur de votre organisation crée les clés dans la console, rubrique « Intégrations ». Les clés appartiennent à l’organisation : chaque administrateur les voit toutes et peut toutes les révoquer.

• La clé est affichée une seule fois, dans la réponse à sa création. Rangez-la dans votre gestionnaire de secrets : elle ne pourra plus être affichée.
• Chaque clé a une date d’expiration, au plus 366 jours après sa création.
• Une organisation détient au plus 20 clés non révoquées, clés expirées comprises.

Utilisez une clé par application. Vous pourrez ainsi en révoquer une sans toucher aux autres.

Droits

Une clé porte un ou plusieurs droits (scopes), choisis à sa création. Chaque opération demande l’un d’eux :

Développer un événement lié (expand[]=event) demande aussi events_read. Une clé à qui manque le droit d’une opération reçoit 403 api_key_scope_missing, dont le message nomme le droit manquant.

Pour voir les droits et l’expiration de la clé que vous utilisez, appelez GET/v1/account :

{
  "id": "ORG-7b2c9e40-1a5d-4c83-9f6e-3d8a0b4c2e71",
  "object": "account",
  "api_key": {
    "id": "APIK-4f8a2c1e-9b3d-4e6a-8c7f-2a1e5d9b0c34",
    "scopes": [
      "calls_for_papers_read",
      "events_read",
      "registrations_read"
    ],
    "expires_at": 1824076800
  }
}

expires_at est un horodatage Unix, en secondes.

Expiration et révocation

Un administrateur révoque une clé dans la console. La révocation est définitive : créez une nouvelle clé plutôt que de chercher à rétablir l’ancienne.

Une clé révoquée ou expirée cesse de fonctionner en moins de 60 secondes. Pendant cette minute, des appels faits avec elle peuvent encore aboutir.

Pour remplacer une clé sans interruption :

1. Créez la nouvelle clé.
2. Déployez-la dans votre application.
3. Révoquez l’ancienne.

Erreurs d’authentification

• 401 api_key_invalid : l’en-tête est absent ou mal formé, ou la clé est inconnue, révoquée ou expirée. Tous ces cas reçoivent la même réponse, volontairement : l’API ne dit jamais lequel.
• 402 plan_feature_missing : l’offre de votre organisation n’inclut pas l’API. Les appels à communications et les communications demandent aussi le module des appels à communications de l’offre.
• 423 organization_suspended : votre organisation est suspendue. Chaque appel renvoie cette erreur jusqu’à sa réactivation.

Un seul document se passe de clé : le contrat lui-même, GET /v1/openapi.json.