Authentification

Créez une clé API pour votre site et utilisez-la dans vos appels.

Chaque appel à l’API est authentifié par une clé. Une clé donne accès aux articles d’un seul site : celui choisi à sa création.

Créer une clé

Qui peut créer une clé

Le propriétaire et les administrateurs de l’organisation, pour tous les sites.
Les membres qui ont la permission Gérer les clés API sur un site, pour ce site uniquement.

Pour accorder cette permission, ouvrez les permissions du membre depuis Membres, puis activez Gérer les clés API sur le site. Une clé donne accès aux articles de tous les Oscars du site : la permission n’est donc disponible que si le membre voit le site en entier, c’est-à-dire :

un accès au site en Lecture ou en Écriture ;
aucun Oscar du site réglé sur Aucun ;
l’option Donner accès aux futurs oscars activée.

La page Membres et permissions détaille ces réglages.

Créer la clé

Dans la section Organisation du menu, ouvrez Clés API.
Cliquez sur Créer une clé.
Choisissez le Site et donnez un Nom à la clé, par exemple celui de l’outil qui l’utilisera.
Dans la fenêtre Votre nouvelle clé API, copiez la clé, puis cliquez sur J’ai copié ma clé.

Un site peut avoir 3 clés actives au maximum. Utilisez une clé par outil : vous pourrez en révoquer une sans interrompre les autres.

Une clé appartient au site

Une clé reste valable si la personne qui l’a créée quitte l’organisation ou perd ses droits, et si le site se connecte plus tard à un CMS. Elle cesse de fonctionner quand elle est révoquée ou quand le site est supprimé.

Envoyer la clé

Envoyez la clé dans l’en-tête Authorization de chaque requête, précédée de Bearer :

GET /v1/articles HTTP/1.1
Host: beta-api.oscar-seo.ai
Authorization: Bearer osk_votre_cle

Les exemples du premier appel montrent cet en-tête en curl, en PHP et en JavaScript.

Si la clé est absente, mal formée, inconnue ou révoquée, l’API répond avec le statut 401 :

{ "error": "INVALID_API_KEY" }

Protéger votre clé

Une clé donne accès à tous les articles du site. Traitez-la comme un mot de passe :

Utilisez-la uniquement dans du code exécuté sur votre serveur. Ne la placez jamais dans du code exécuté par le navigateur, comme le JavaScript d’une page : n’importe quel visiteur pourrait la lire.
N’écrivez pas la clé dans votre code source et ne l’enregistrez pas dans un dépôt Git. Stockez-la dans une variable d’environnement ou dans un fichier de configuration placé hors du dossier public de votre site.
Ne la transmettez pas par e-mail ni par messagerie.

Pour lire la clé depuis une variable d’environnement OSCAR_API_KEY, remplacez la clé écrite en dur dans les exemples :

curl "https://beta-api.oscar-seo.ai/v1/articles?pageSize=1" \
  -H "Authorization: Bearer $OSCAR_API_KEY"

$apiKey = getenv('OSCAR_API_KEY');

const apiKey = process.env.OSCAR_API_KEY

La façon de définir cette variable dépend de votre hébergement : panneau d’administration de l’hébergeur, configuration du serveur ou de la tâche planifiée qui lance votre script.

Révoquer une clé

Révoquez une clé dès que vous pensez qu’elle a fuité, ou quand l’outil qui l’utilisait n’en a plus besoin.

Dans la section Organisation du menu, ouvrez Clés API.
Dans le menu d’actions de la clé, choisissez Révoquer.
Confirmez avec Révoquer.

La révocation prend effet immédiatement et ne peut pas être annulée : les appels faits avec cette clé reçoivent une erreur 401 INVALID_API_KEY. La clé reste dans la liste avec le statut Révoquée, l’auteur de la révocation et sa date. Une clé révoquée par l’équipe Oscar porte la mention « par l’équipe Oscar ».

Les personnes qui peuvent créer une clé pour un site peuvent aussi révoquer toutes les clés de ce site.

Remplacer une clé sans interruption

Créez une nouvelle clé pour le même site.
Mettez-la en place dans votre script.
Vérifiez que la colonne Dernière utilisation de la nouvelle clé se remplit.
Révoquez l’ancienne clé.

Si le site a déjà 3 clés actives, révoquez d’abord une clé que vous n’utilisez plus.