Clés API

Les clés API permettent d'accéder à vos données BeePass depuis des applications externes, scripts ou intégrations tierces sans passer par l'interface web. Chaque clé dispose de permissions granulaires par ressource.

Fonctionnement

[Votre application]
    │ Authorization: Bearer bp_live_a3f8...5e82
    ▼
https://beepass.io/api/v1/queens
    │ Validation SHA-256 → lookup DB → check permissions
    ▼
[Données retournées en JSON]

Créez une clé depuis l'interface web (menu avatar → Clés API)
Copiez la clé — elle ne sera affichée qu'une seule fois
Utilisez-la dans l'en-tête Authorization de vos requêtes

Format de clé

bp_live_ + 64 caractères hexadécimaux = 72 caractères

Exemple : bp_live_a3f8e2b1c4d5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1

Sécurité

La clé brute n'est affichée qu'une seule fois lors de la création. BeePass ne stocke qu'un hash SHA-256 — il est impossible de récupérer une clé perdue. Vous devrez en créer une nouvelle.

Utilisation

Ajoutez la clé dans l'en-tête Authorization de chaque requête :

curl -H "Authorization: Bearer bp_live_a3f8..." \
     https://beepass.io/api/v1/queens

const response = await fetch('https://beepass.io/api/v1/queens', {
  headers: {
    'Authorization': 'Bearer bp_live_a3f8...',
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

import requests

headers = {
    'Authorization': 'Bearer bp_live_a3f8...',
    'Content-Type': 'application/json'
}
response = requests.get('https://beepass.io/api/v1/queens', headers=headers)
data = response.json()

Permissions

Chaque clé définit un niveau d'accès par ressource :

Ressource	Description
Queens	Reines F0 et F1 (souches, production)
Evaluations	Évaluations de performance
BLUP	Valeurs génétiques estimées (EBV)
Hive	Ruchers et ruches
Account	Profil et paramètres du compte

Niveaux de permission

Niveau	Lecture (GET)	Écriture (POST/PUT/DELETE)
Aucun	-	-
Lecture	Oui	-
Écriture	Oui	✅

astuce

Le niveau Écriture inclut automatiquement la lecture. Pas besoin de définir les deux.

Modèles prédéfinis

Modèle	Description	Permissions
Lecture seule	Consultation de toutes les données	Toutes les ressources en lecture
Évaluateur	Saisie d'évaluations terrain	Évaluations en écriture, reste en lecture (sauf Rucher)
Personnalisé	Configuration manuelle	Vous choisissez chaque permission

Restrictions

Expiration (TTL)

Définissez une durée de vie pour votre clé :

Option	Description
7 jours	Tests et développement
30 jours	Intégrations temporaires
90 jours	Usage standard
365 jours	Intégrations long terme
Jamais	Pas d'expiration automatique

Une clé expirée est automatiquement rejetée. Elle reste visible dans la liste mais avec le statut "Expiré".

Restriction IP

Limitez l'utilisation d'une clé à des adresses IP spécifiques pour renforcer la sécurité :

IP unique : 203.0.113.5
Sous-réseau CIDR : 192.168.1.0/24

Si aucune IP n'est définie, la clé peut être utilisée depuis n'importe quelle adresse.

info

La restriction IP est vérifiée à chaque requête. L'IP du client est extraite des en-têtes CF-Connecting-IP, X-Forwarded-For ou X-Real-IP.

Gestion des clés

Créer une clé

Accédez à la page Clés API depuis le menu avatar dans le header, puis cliquez sur Générer une clé. Le wizard en 4 étapes vous guide :

Nom — Choisissez un nom descriptif et un modèle de permissions
Permissions — Ajustez les permissions par ressource (mode personnalisé)
Restrictions — Définissez l'expiration et les IPs autorisées
Clé générée — Copiez votre clé immédiatement

Désactiver / Réactiver

Utilisez le switch dans la colonne "Activer" du tableau pour désactiver temporairement une clé sans la supprimer. Une clé désactivée est immédiatement rejetée par l'API.

Révoquer

Cliquez sur l'icône corbeille puis confirmez la révocation. La clé passe en statut "Révoqué" et ne peut plus être réactivée.

Limites

Limite	Valeur
Nombre max de clés par utilisateur	20
Créations par heure	10
Longueur du nom	1 à 100 caractères

API de gestion

Les clés sont gérées via l'API REST standard (authentification par session Supabase) :

Méthode	Route	Description
`GET`	`/api/api-keys`	Lister vos clés (sans le hash)
`POST`	`/api/api-keys`	Créer une nouvelle clé
`PUT`	`/api/api-keys/{id}`	Modifier le nom ou le statut
`DELETE`	`/api/api-keys`	Révoquer une clé

Créer une clé (POST)

curl -X POST https://beepass.io/api/api-keys \
  -H "Content-Type: application/json" \
  -b "sb-cookie=..." \
  -d '{
    "name": "Mon app mobile",
    "permissions": {
      "queens": "read",
      "evaluations": "write",
      "blup": "read",
      "hive": "none",
      "account": "read"
    },
    "expires_in_days": 90,
    "ip_allowlist": ["203.0.113.0/24"]
  }'

Réponse (201) :

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "bp_live_a3f8e2b1c4d5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
    "key_prefix": "bp_live_a3f8e2b1...f0a1"
  }
}

Révoquer une clé (DELETE)

curl -X DELETE https://beepass.io/api/api-keys \
  -H "Content-Type: application/json" \
  -b "sb-cookie=..." \
  -d '{ "id": "550e8400-e29b-41d4-a716-446655440000" }'

Codes d'erreur

Code	Situation
`400`	Paramètres invalides (nom, permissions, TTL, IP)
`400`	Maximum 20 clés atteint
`401`	Session non authentifiée
`429`	Limite de création dépassée (10/h)

Permissions détaillées

Chaque ressource accepte trois niveaux d'accès. Le niveau write inclut automatiquement la lecture.

Ressource	`none`	`read`	`write`
`queens`	Aucun accès	Lire les reines	Créer/modifier des reines
`evaluations`	Aucun accès	Lire les évaluations	Soumettre des évaluations
`blup`	Aucun accès	Lire les EBV	—
`hive`	Aucun accès	Lire les ruchers	Modifier les ruchers
`account`	Aucun accès	Lire le profil	Modifier le profil

info

La ressource blup ne propose pas de niveau write. Les valeurs génétiques sont calculées par le pipeline et ne peuvent pas être modifiées via l'API.

Restriction par IP

Vous pouvez limiter l'utilisation d'une clé à une liste d'adresses IP autorisées (allowlist). La notation CIDR est supportée pour autoriser un sous-réseau entier.

Exemples de valeurs acceptées :

203.0.113.5 -- une seule adresse IP
192.168.1.0/24 -- tout le sous-réseau 192.168.1.x (256 adresses)
10.0.0.0/8 -- tout le réseau privé 10.x.x.x

Si la liste est vide, la clé est utilisable depuis n'importe quelle adresse. L'adresse du client est extraite via les en-têtes CF-Connecting-IP, X-Forwarded-For ou X-Real-IP.

Durée de validité

Chaque clé dispose d'une durée de vie (TTL) définie à la création :

Durée	Cas d'usage
7 jours	Tests et prototypage
30 jours	Intégrations ponctuelles
90 jours	Usage courant
1 an	Intégrations stables
Illimitée	Pas d'expiration automatique

Une clé expirée est automatiquement rejetée par l'API avec le code HTTP 401. Elle reste visible dans votre liste de clés avec le statut Expiré, mais ne peut plus être réactivée. Vous devrez en créer une nouvelle.

attention

La clé brute n'est affichée qu'une seule fois lors de la création. Copiez-la immédiatement et stockez-la dans un gestionnaire de secrets. BeePass ne conserve qu'un hash SHA-256 : il est impossible de récupérer une clé perdue.

Voir aussi : Vue d'ensemble | Authentification | Reines | Évaluations

Fonctionnement​

Format de clé​

Utilisation​

Permissions​

Niveaux de permission​

Modèles prédéfinis​

Restrictions​

Expiration (TTL)​

Restriction IP​

Gestion des clés​

Créer une clé​

Désactiver / Réactiver​

Révoquer​

Limites​

API de gestion​

Créer une clé (POST)​

Révoquer une clé (DELETE)​

Codes d'erreur​

Permissions détaillées​

Restriction par IP​

Durée de validité​