Clés API

Les clés API permettent d’appeler une partie de l’API REST himydata (/v1/...) depuis un script, un ETL ou une intégration externe — sans session utilisateur JWT.

Créer une clé

Depuis l’interface

1. Ouvrez Paramètres → Organisation
2. Onglet Clés API
3. Cliquez sur Créer une clé, renseignez le nom, l’environnement, les scopes et l’expiration éventuelle
4. Copiez le secret immédiatement — il ne sera plus affiché ensuite

Seuls les rôles admin et integrator peuvent créer et lister des clés. Les members n’y ont pas accès.

Depuis l’API (JWT)

curl -sS -X POST "https://api.himydata.com/v1/organizations/api-keys" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "integration-etl",
    "environment": "live",
    "scopes": ["read", "write"],
    "expires_at": null
  }'

La réponse contient api_key (secret complet), key_prefix, id et un warning rappelant que le secret ne sera plus visible. Référence interactive : endpoints de gestion.

Format du secret

hmd_{environment}_{secret}

Exemple : hmd_live_a1b2c3d4e5f6…. Seul un préfixe (12 caractères) est conservé côté serveur ; le secret complet n’est jamais re-stocké.

Authentifier vos appels

Authorization: Bearer hmd_live_…

Utilisez la clé API à la place du JWT sur les endpoints autorisés (voir ci-dessous). Les autres routes restent réservées au JWT utilisateur.

Permissions

Une clé n’a jamais plus de droits que la personne qui l’a créée, au moment de l’appel :

scopes effectifs = scopes de la clé ∩ droits du rôle du créateur

En pratique :

• Si le créateur est rétrogradé ou retiré de l’organisation, la clé perd des droits ou cesse de fonctionner.
• Sur la Data API, les contrôles d’accès aux datasets s’appliquent comme si le créateur appelait l’API en JWT (permissions dataset, colonnes autorisées, etc.). Une clé ne donne pas un accès « org-wide » automatique.
• Si le créateur n’existe plus, la clé est refusée.

Scopes

Attribuer execute ou manage n’apporte donc aucun pouvoir supplémentaire dans la version actuelle.

Endpoints accessibles avec une clé API

Lecture (read)

Référence détaillée : module Datasets.

Sous clé API, le champ is_favorite est omis des réponses /data (il refléterait les favoris du créateur, pas de la clé).

Écriture (write)

Hors périmètre (JWT uniquement)

• Création / configuration de datasets, sync, permissions, audit
• Agents, documents, dashboards, connexions, organisation
• Complétion SQL (/datasets/sql/completion)
• Gestion des clés elles-mêmes (/organizations/api-keys)

Environnements

L’environnement choisi à la création doit correspondre au serveur que vous appelez. Une clé hmd_test_… ne fonctionne pas sur l’API de production.

Révoquer une clé

• Interface : bouton Révoquer sur la ligne de la clé
• API (JWT) : DELETE /v1/organizations/api-keys/{id}

La révocation est immédiate et irréversible. Un appel sur une clé déjà révoquée renvoie une réponse OK (idempotent).

Un admin peut révoquer toute clé de l’organisation. Un integrator ne peut révoquer que ses propres clés.

Exemples

BASE_URL="https://api.himydata.com/v1"
API_KEY="hmd_live_xxxxxxxxxxxxxxxxxxxxxxxx"
DATASET_ID="550e8400-e29b-41d4-a716-446655440000"

Lister les datasets

curl -sS "${BASE_URL}/datasets?limit=10" \
  -H "Authorization: Bearer ${API_KEY}"

Lire des lignes

curl -sS "${BASE_URL}/datasets/${DATASET_ID}/data?limit=10&offset=0" \
  -H "Authorization: Bearer ${API_KEY}"

Exporter en CSV

curl -sS "${BASE_URL}/datasets/${DATASET_ID}/export?format=csv" \
  -H "Authorization: Bearer ${API_KEY}" \
  -o export.csv

Insérer une ligne

curl -sS -X POST "${BASE_URL}/datasets/${DATASET_ID}/rows" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"data": {"id": 1, "label": "demo"}}'

Python (httpx)

import httpx

BASE = "https://api.himydata.com/v1"
API_KEY = "hmd_live_…"
DATASET_ID = "550e8400-e29b-41d4-a716-446655440000"

headers = {"Authorization": f"Bearer {API_KEY}"}

with httpx.Client(base_url=BASE, headers=headers, timeout=30.0) as client:
    rows = client.get(f"/datasets/{DATASET_ID}/data", params={"limit": 10})
    rows.raise_for_status()

    inserted = client.post(
        f"/datasets/{DATASET_ID}/rows",
        json={"data": {"id": 42, "label": "from-script"}},
    )
    inserted.raise_for_status()
    print(inserted.json())  # {"inserted": 1}

La création et la révocation de clés restent en JWT — voir Gestion des clés (REST).

Bonnes pratiques

• Ne commitez jamais une clé dans un dépôt ; utilisez des variables d’environnement ou un coffre de secrets.
• Accordez le minimum de scopes nécessaires (read seul si vous ne faites que de la lecture).
• Définissez une date d’expiration pour les intégrations temporaires.
• Révoquez immédiatement toute clé compromise.