Schnellstart

Von null zu Ihrem ersten authentifizierten Aufruf der öffentlichen Kabeen-API in rund fünf Minuten

Von null zu Ihrem ersten authentifizierten Aufruf der öffentlichen Kabeen-API in rund fünf Minuten. Setzen Sie Ihren eigenen API-Schlüssel und Host ein — jedes Beispiel unten ist dann unverändert kopierbar.

1. Voraussetzungen

Sie benötigen:

  • Einen Kabeen-Workspace.
  • Einen API-Schlüssel, erstellt von einem Workspace-Admin innerhalb der Kabeen-App. Schlüssel sind Workspace-gebunden (werden nie im Pfad oder Body übergeben) und tragen einen Satz von Berechtigungs-Scopes (z. B. applications:read, applications:add). Wie Schlüssel ausgestellt, rotiert und mit Scopes versehen werden, steht unter Authentifizierung.

Jede Anfrage wird mit einem der beiden Header authentifiziert — wählen Sie einen und bleiben Sie dabei:

Authorization: Bearer kbn_live_...

oder

X-Api-Key: kbn_live_...

Exportieren Sie Ihren Schlüssel und Host als Umgebungsvariablen, damit jedes Snippet unten direkt funktioniert:

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

Alle Anfragen gehen an:

https://{KABEEN_HOST}/public/v1

2. Schlüssel überprüfen

Bestätigen Sie zuallererst, dass der Schlüssel funktioniert, und sehen Sie genau, was er darf. GET /me erfordert keinen bestimmten Scope — jeder gültige Schlüssel kann den Endpunkt aufrufen.

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

Antwort:

{
  "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"
  ]
}

Zwei Dinge lohnen einen Blick, bevor Sie weitermachen:

  • workspace ist der Workspace, an den Ihr Schlüssel gebunden ist — es gibt keine Möglichkeit, mit demselben Schlüssel einen anderen anzusprechen.
  • permissions ist die exakte Liste der Scopes, die dieser Schlüssel gewährt. Ist der gewünschte Aufruf davon nicht abgedeckt, erhalten Sie einen 403 und benötigen einen neuen Schlüssel mit breiterem Scope.

3. Eine Ressource auflisten

Listen-Endpunkte haben in der gesamten API dieselbe Form. Listen wir Anwendungen auf (erfordert 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
  }
}

Der Umschlag ist immer { "data": [...], "pagination": {...} }:

  • data — ein Array schlanker, listentauglicher Einträge. Für die ausführliche Version rufen Sie die einzelne Ressource ab — siehe Schritt 4.
  • pagination — limit (Ihr angefragter Wert, begrenzt auf [1, 200]), offset (Ihr angefragter Wert, mindestens 0) und total (wie viele Einträge über alle Seiten hinweg passen, nicht nur diese). Erhöhen Sie offset jeweils um limit, um den Rest der Liste zu durchlaufen. Alle Details unter Paginierung und Fehler.

GET /applications akzeptiert außerdem search, categoryId, criticality, hostingType, tag, teamId, sort und direction als Query-Filter — siehe die Endpunkt-Referenz.

4. Eine einzelne Ressource abrufen

Listeneinträge sind bewusst schlank. Rufen Sie eine einzelne Anwendung per Id ab, um den vollständigen Detaildatensatz zu erhalten — Kategorie, Anbieter, Tags, Verantwortliche, Lebenszyklus, Support-/Authentifizierungsinformationen und benutzerdefinierte Felder (erfordert Scope applications:read):

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

Antwort (gekürzt):

{
  "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. Anlegen und aktualisieren

Schreibvorgänge benötigen den spezifischen Scope für die Aktion, nicht nur applications:read.

Eine Anwendung anlegen — erfordert Scope applications:add. Nur name ist erforderlich:

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

Die Antwort ist eine schlanke Projektion der angelegten Anwendung:

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

Sie aktualisieren — erfordert Scope applications:edit. PATCH ändert nur die Felder, die Sie senden; ein JSON-null wird als „nicht angegeben" behandelt, ein Feld lässt sich auf diesem Weg also nicht leeren:

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"
  }'

Die Antwort ist diesmal das vollständige Anwendungsdetail (dieselbe Form wie in Schritt 4), mit Ihrer Änderung.

6. Fehler und Paginierung behandeln

  • Jede 4xx/5xx-Antwort hat dieselbe JSON-Form: { "code", "message", "status" }. Prüfen Sie code für die programmatische Behandlung — er bleibt über Releases hinweg stabil, auch wenn sich die Formulierung von message ändert. Die einzige Ausnahme ist 401, der mit leerem Body zurückkommt.
  • Die zwei Fehler, denen Sie beim Integrieren ständig begegnen: 401 (falscher oder fehlender Schlüssel) und 403 (Schlüssel ist gültig, aber ohne den vom Endpunkt geforderten Scope — prüfen Sie permissions aus Schritt 2 erneut).
  • Die Paginierung ist überall offset-basiert, außer beim Audit-Log, das cursor-basiert ist (cursor / nextCursor), weil es append-only ist und hohes Volumen hat.

Vollständige Referenz: Paginierung und Fehler.

7. Derselbe Aufruf in drei Sprachen

Hier GET /applications?limit=10 aus Schritt 3, einmal pro Sprache.

curl

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

JavaScript (Node 18+, globales fetch)

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")

Nächste Schritte

VorherigeAuthentifizierung und API-SchlüsselNächstePaginierung, Fehler und Polling