Inicio rápido

Pase de cero a su primera llamada autenticada a la API pública de Kabeen en unos cinco minutos

Pase de cero a su primera llamada autenticada contra la API pública de Kabeen en unos cinco minutos. Sustituya su propia clave de API y su host, y todos los ejemplos siguientes se pueden copiar y pegar tal cual.

1. Requisitos previos

Necesita:

  • Un espacio de trabajo de Kabeen.
  • Una clave de API, creada por un administrador del espacio de trabajo desde la aplicación Kabeen. Las claves están vinculadas al espacio de trabajo (nunca se pasan en la ruta ni en el cuerpo) y llevan un conjunto de scopes de permisos (p. ej. applications:read, applications:add). Consulte Autenticación para saber cómo se emiten, rotan y delimitan las claves.

Cada petición se autentica con cualquiera de estas dos cabeceras — elija una y manténgala:

Authorization: Bearer kbn_live_...

o

X-Api-Key: kbn_live_...

Exporte su clave y su host como variables de entorno para que todos los fragmentos siguientes funcionen sin cambios:

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

Todas las peticiones se hacen contra:

https://{KABEEN_HOST}/public/v1

2. Verifique su clave

Antes que nada, confirme que la clave funciona y vea exactamente qué se le permite hacer. GET /me no requiere ningún scope específico: cualquier clave válida puede llamarlo.

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

Respuesta:

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

Dos cosas que conviene comprobar antes de continuar:

  • workspace es el espacio de trabajo al que está vinculada su clave: no hay forma de dirigirse a otro con la misma clave.
  • permissions es la lista exacta de scopes que otorga esta clave. Si la llamada que desea no está cubierta por esta lista, obtendrá un 403 y necesitará una nueva clave con un alcance más amplio.

3. Liste un recurso

Los endpoints de listado comparten la misma forma en toda la API. Listemos las aplicaciones (requiere el 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
  }
}

El sobre es siempre { "data": [...], "pagination": {...} }:

  • data — un array de elementos ligeros, pensados para listados. Recupere un recurso individual para obtener la versión enriquecida — vea el paso 4.
  • pagination — limit (lo que solicitó, acotado a [1, 200]), offset (lo que solicitó, con mínimo 0) y total (cuántos elementos coinciden en todas las páginas, no solo en esta). Incremente offset en limit para recorrer el resto de la lista. Detalles completos en Paginación y errores.

GET /applications también acepta search, categoryId, criticality, hostingType, tag, teamId, sort y direction como filtros de consulta — consulte la Referencia de endpoints.

4. Recupere un recurso

Los elementos de listado son deliberadamente ligeros. Recupere una única aplicación por id para obtener la ficha detallada completa: categoría, proveedor, etiquetas, responsables, ciclo de vida, información de soporte/autenticación y campos personalizados (requiere el scope applications:read):

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

Respuesta (recortada):

{
  "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. Cree y actualice

Las escrituras requieren el scope específico de la acción, no basta con applications:read.

Crear una aplicación — requiere el scope applications:add. Solo name es obligatorio:

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 respuesta es una proyección ligera de la aplicación creada:

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

Actualizarla — requiere el scope applications:edit. PATCH solo modifica los campos que envía; un null JSON se trata como "no proporcionado", así que no puede vaciar un campo por esta vía:

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

La respuesta esta vez es el detalle completo de la aplicación (la misma forma que en el paso 4), reflejando su cambio.

6. Gestione errores y paginación

  • Toda respuesta 4xx/5xx tiene la misma forma JSON: { "code", "message", "status" }. Compruebe code para el tratamiento programático: es estable entre versiones aunque cambie la redacción de message. La única excepción es 401, que vuelve con cuerpo vacío.
  • Los dos errores con los que se topará constantemente durante la integración: 401 (clave incorrecta o ausente) y 403 (la clave es válida pero le falta el scope que el endpoint requiere — vuelva a comprobar permissions del paso 2).
  • La paginación es por offset en todas partes salvo en el registro de auditoría, que usa cursor (cursor / nextCursor) por ser de solo anexado y de gran volumen.

Referencia completa: Paginación y errores.

7. La misma llamada en tres lenguajes

Aquí tiene el GET /applications?limit=10 del paso 3, una vez en cada lenguaje.

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

Próximos pasos

AnteriorAutenticación y claves de APISiguientePaginación, errores y sondeo