Clés API

Toutes les requêtes vers https://api.mitoera.com/api sont authentifiées par une clé. Il en existe deux types, aux pouvoirs volontairement très différents.

Les deux types de clés

Clé secrète — portée backoffice

pk_xxxxxxxx:sk_xxxxxxxx

Accès complet en lecture et en écriture : plans, événements, réservations, catégories, workspaces. C'est elle qui confirme les réservations.

À utiliser uniquement côté serveur. Jamais dans du JavaScript envoyé au navigateur, jamais dans un dépôt Git, jamais dans une URL.

Clé publique — portée public

pk_live_xxxxxxxx   (production)
pk_test_xxxxxxxx   (sandbox)

Lecture seule, destinée au widget côté client. Elle peut être exposée dans votre code front-end : elle ne permet ni de modifier un plan, ni de confirmer une réservation.

Créer une clé

Dans le back-office : Clés API → Nouvelle clé, en choisissant la portée. Le secret n'est affiché qu'une seule fois, à la création — copiez-le immédiatement.

Le SDK sait aussi le faire, si vous automatisez le provisionnement de vos workspaces :

JavaScript / TypeScript

const created = await client.apiKeys.create('Serveur de prod', 'BACKOFFICE');
created.secret;   // visible une seule fois

await client.apiKeys.listAll();
await client.apiKeys.delete(apiKeyId);

PHP

$created = $client->apiKeys->create('Serveur de prod', 'BACKOFFICE');
$created->secret;   // visible une seule fois

$client->apiKeys->listAll();
$client->apiKeys->delete($apiKeyId);

S'authentifier en HTTP

L'API utilise l'authentification HTTP Basic : keyId en identifiant, secret en mot de passe.

Authorization: Basic {base64(keyId:secret)}

cURL

curl https://api.mitoera.com/api/charts \
  -u pk_xxxxxxxx:sk_xxxxxxxx

fetch

const res = await fetch('https://api.mitoera.com/api/charts', {
  headers: {
    Authorization: `Basic ${btoa('pk_xxxxxxxx:sk_xxxxxxxx')}`,
  },
});
const charts = await res.json();

PHP natif

$ch = curl_init('https://api.mitoera.com/api/charts');
curl_setopt($ch, CURLOPT_USERPWD, 'pk_xxxxxxxx:sk_xxxxxxxx');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$charts = json_decode(curl_exec($ch), true);

Les SDK construisent ce header pour vous : vous ne passez que keyId et secret au constructeur.

Portée d'une clé

Une clé est liée à un workspace. Toutes les ressources qu'elle lit ou écrit appartiennent à ce workspace, sans que vous ayez à le préciser dans vos requêtes. Une clé d'un workspace A qui tente de lire une ressource du workspace B reçoit un 403.

Bonnes pratiques

Une clé par environnement. Une clé pour la production, une pour la préproduction, une pour le poste de chaque développeur. Une fuite se révoque alors sans tout casser.

Variables d'environnement. MITOERA_KEY_ID et MITOERA_SECRET dans votre .env, jamais en dur dans le code.

Révocation immédiate en cas de doute. Supprimez la clé dans le back-office ou via apiKeys.delete() : l'effet est instantané. Créez-en une nouvelle et redéployez.

Les clés de production supposent un plan actif. Sans abonnement, leur création est refusée et les clés existantes sont suspendues — puis rétablies automatiquement si le paiement reprend. Les clés pk_test_ de la sandbox restent disponibles en permanence.

Un 401 vous dit pourquoi. Le corps nomme la cause — invalid_key, invalid_secret, key_revoked, malformed_credentials — avec un hint qui indique le correctif. Voir Codes d'erreur plutôt que de deviner.

Le préfixe indique l'environnement. pk_test_ route vers la sandbox, pk_live_ vers la production. Les SDK et le widget le détectent seuls — vous n'avez aucun réglage supplémentaire à faire.