Démarrage rapide

Passez de zéro à votre premier appel authentifié à l'API publique Kabeen en environ cinq minutes

Passez de zéro à votre premier appel authentifié contre l'API publique Kabeen en environ cinq minutes. Remplacez la clé d'API et l'hôte par les vôtres, et chaque exemple ci-dessous est directement copiable-collable.

1. Prérequis

Il vous faut :

  • Un espace de travail Kabeen.
  • Une clé d'API, créée par un administrateur de l'espace de travail depuis l'application Kabeen. Les clés sont liées à un espace de travail (jamais passé dans le chemin ni le corps) et portent un ensemble de scopes de permission (par exemple applications:read, applications:add). Voir Authentification pour la création, la rotation et la délimitation des clés.

Chaque requête est authentifiée avec l'un des deux en-têtes — choisissez-en un et gardez-le :

Authorization: Bearer kbn_live_...

ou

X-Api-Key: kbn_live_...

Exportez votre clé et votre hôte comme variables d'environnement pour que chaque extrait ci-dessous fonctionne tel quel :

export KABEEN_API_KEY="kbn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export KABEEN_HOST="app.kabeen.io"

Toutes les requêtes sont adressées à :

https://{KABEEN_HOST}/public/v1

2. Vérifiez votre clé

Avant toute chose, confirmez que la clé fonctionne et voyez exactement ce qu'elle est autorisée à faire. GET /me ne requiert aucun scope particulier — toute clé valide peut l'appeler.

curl -s "https://${KABEEN_HOST}/public/v1/me" \
  -H "Authorization: Bearer ${KABEEN_API_KEY}"

Réponse :

{
  "workspace": {
    "id": "8f0a2b1e-2b8b-4e2a-9c3e-1a2b3c4d5e6f",
    "name": "Acme Corp"
  },
  "key": {
    "id": "3c9d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
    "name": "CMDB sync",
    "alias": "read"
  },
  "permissions": [
    "applications:read",
    "contracts:read",
    "infrastructure:read"
  ]
}

Deux points à vérifier avant d'aller plus loin :

  • workspace est l'espace de travail auquel votre clé est liée — il n'existe aucun moyen d'en adresser un autre avec la même clé.
  • permissions est la liste exacte des scopes accordés par cette clé. Si l'appel que vous visez n'est pas couvert par cette liste, vous obtiendrez un 403 et il vous faudra une nouvelle clé avec un scope plus large.

3. Lister une ressource

Les endpoints de liste partagent la même forme sur toute l'API. Listons les applications (requiert le scope applications:read) :

curl -s "https://${KABEEN_HOST}/public/v1/applications?limit=10" \
  -H "Authorization: Bearer ${KABEEN_API_KEY}"
{
  "data": [
    {
      "id": "1b2c3d4e-5f60-4a1b-8c2d-3e4f5a6b7c8d",
      "name": "Salesforce",
      "description": "CRM platform",
      "logo": "https://cdn.kabeen.io/logos/salesforce.png",
      "state": "active",
      "criticality": "high",
      "hostingType": "saas",
      "category": {
        "id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
        "name": "CRM"
      }
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 42
  }
}

L'enveloppe est toujours { "data": [...], "pagination": {...} } :

  • data — un tableau d'éléments allégés, adaptés aux listes. Récupérez une ressource individuelle pour la version enrichie — voir l'étape 4.
  • pagination — limit (ce que vous avez demandé, borné à [1, 200]), offset (ce que vous avez demandé, avec un plancher à 0) et total (le nombre d'éléments correspondants sur toutes les pages, pas uniquement celle-ci). Incrémentez offset de limit pour parcourir le reste de la liste. Détails complets dans Pagination et erreurs.

GET /applications accepte aussi search, categoryId, criticality, hostingType, tag, teamId, sort et direction comme filtres de requête — voir la Référence des endpoints.

4. Récupérer une ressource

Les éléments de liste sont volontairement allégés. Récupérez une application par son id pour obtenir la fiche détaillée complète — catégorie, éditeur, tags, responsables, cycle de vie, informations de support/authentification et champs personnalisés (requiert le scope applications:read) :

curl -s "https://${KABEEN_HOST}/public/v1/applications/1b2c3d4e-5f60-4a1b-8c2d-3e4f5a6b7c8d" \
  -H "Authorization: Bearer ${KABEEN_API_KEY}"

Réponse (tronquée) :

{
  "id": "1b2c3d4e-5f60-4a1b-8c2d-3e4f5a6b7c8d",
  "name": "Salesforce",
  "description": "CRM platform",
  "logo": "https://cdn.kabeen.io/logos/salesforce.png",
  "state": "active",
  "criticality": "high",
  "hostingType": "saas",
  "accessUrl": "https://acme.salesforce.com",
  "usageActivated": true,
  "desktopApplicationNames": [],
  "support": { "phone": null, "email": "support@salesforce.com", "url": null },
  "authentication": { "type": "login_password" },
  "category": { "id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d", "name": "CRM" },
  "vendor": { "id": "5e4f3a2b-1c0d-9e8f-7a6b-5c4d3e2f1a0b", "name": "Salesforce Inc." },
  "tags": [{ "id": "tag-1", "name": "critical" }],
  "owners": [],
  "lifecycle": null,
  "customFields": [],
  "updatedAt": "2026-07-15T10:22:00Z"
}

5. Créer et mettre à jour

Les écritures exigent le scope spécifique à l'action, pas seulement applications:read.

Créer une application — requiert le scope applications:add. Seul name est obligatoire :

curl -s -X POST "https://${KABEEN_HOST}/public/v1/applications" \
  -H "Authorization: Bearer ${KABEEN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Zoom"
  }'

La réponse est une projection allégée de l'application créée :

{
  "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
  "name": "Zoom",
  "description": null,
  "criticality": null,
  "logo": "https://cdn.kabeen.io/logos/default.png"
}

Mettre à jour — requiert le scope applications:edit. PATCH ne modifie que les champs que vous envoyez ; un null JSON est traité comme « non fourni », vous ne pouvez donc pas vider un champ de cette façon :

curl -s -X PATCH "https://${KABEEN_HOST}/public/v1/applications/2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f" \
  -H "Authorization: Bearer ${KABEEN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "criticality": "high",
    "accessUrl": "https://zoom.us"
  }'

Cette fois, la réponse est la fiche détaillée complète de l'application (même forme qu'à l'étape 4), reflétant votre modification.

6. Gérer les erreurs et la pagination

  • Chaque réponse 4xx/5xx a la même forme JSON : { "code", "message", "status" }. Testez code pour le traitement programmatique — il est stable d'une version à l'autre, même si la formulation de message change. La seule exception est 401, qui revient avec un corps vide.
  • Les deux erreurs que vous rencontrerez constamment pendant l'intégration : 401 (clé invalide ou absente) et 403 (clé valide mais dépourvue du scope requis par l'endpoint — revérifiez permissions depuis l'étape 2).
  • La pagination est par offset partout, sauf pour le journal d'audit, qui est paginé par curseur (cursor / nextCursor) car il est en ajout continu et à fort volume.

Référence complète : Pagination et erreurs.

7. Le même appel dans trois langages

Voici GET /applications?limit=10 de l'étape 3, une fois dans chaque langage.

curl

curl -s "https://${KABEEN_HOST}/public/v1/applications?limit=10" \
  -H "Authorization: Bearer ${KABEEN_API_KEY}"

JavaScript (Node 18+, fetch global)

const host = process.env.KABEEN_HOST ?? "app.kabeen.io";
const apiKey = process.env.KABEEN_API_KEY;
 
const response = await fetch(`https://${host}/public/v1/applications?limit=10`, {
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
});
 
if (!response.ok) {
  const problem = await response.json();
  throw new Error(`${problem.code}: ${problem.message}`);
}
 
const { data, pagination } = await response.json();
console.log(`Got ${data.length} of ${pagination.total} applications`);

Python (requests)

import os
import requests
 
host = os.environ.get("KABEEN_HOST", "app.kabeen.io")
api_key = os.environ["KABEEN_API_KEY"]
 
response = requests.get(
    f"https://{host}/public/v1/applications",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"limit": 10},
)
response.raise_for_status()
 
body = response.json()
print(f"Got {len(body['data'])} of {body['pagination']['total']} applications")

La suite

PrécédentAuthentification et clés d'APISuivantPagination, erreurs et polling