Kordia

Autenticación

La API usa claves por organización. La clave determina la organización activa, por lo que no debes enviar organization_id en los payloads.

REST requiere una suscripción Starter o Pro en estado interno active; MCP requiere Pro. Se comprueba en cada petición, incluso con una clave ya existente. Free y las suscripciones sin estado activo no habilitan el acceso. Al bajar de Pro a Starter, la misma clave conserva el acceso REST pero pierde MCP. No se utiliza OAuth: el Bearer es una API key de organización.

Crear una API key

  1. Entra en Kordia con un usuario administrador.
  2. Abre la organización.
  3. Abre el desplegable del usuario.
  4. Ve a API keys.
  5. Crea una clave con un nombre identificable y elige por área: Sin acceso, Solo lectura o Lectura y escritura. Por defecto se selecciona solo lectura. En el listado, «Ver permisos» muestra el acceso efectivo de cada clave creada.

El enlace API keys solo aparece para administradores con Starter o Pro activo. Si la organización está en Free o la suscripción deja de estar activa, la URL directa redirige a Suscripción y no permite generar claves. 6. Copia el token en ese momento. No se vuelve a mostrar.

Las claves se guardan hasheadas. Si pierdes una clave, revócala y crea otra.

Scopes

Cada área ofrece scopes :read y :write: projects, resources, contracts, tags, assignments, organization y members. Escribir implica leer esa misma área: projects:write también concede projects:read. Esto se aplica a las claves existentes sin regenerarlas. Leer no concede escritura, ni se amplían permisos a otras áreas.

  • Planificar asignaciones: assignments:read.
  • Previsualizar contratos: contracts:read.
  • Informes project_hours y tag_breakdown: projects:read.
  • Informes resource_hours y availability: resources:read.
  • Actualizar organización: organization:write y creador de clave actualmente administrador.
  • Miembros e invitaciones: members:read para listar, members:write para mutar, siempre con creador de clave actualmente administrador. Invitar envía correo.

Las claves antiguas mantienen sus scopes; no se amplían automáticamente. Crea una nueva clave con los permisos explícitos que necesite la integración. Usa el menor privilegio posible.

Cabecera recomendada

Authorization: Bearer kordia_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

También se acepta:

X-API-Key: kordia_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl https://app.example.com/api/v1/projects \
  -H "Authorization: Bearer $KORDIA_API_KEY" \
  -H "Accept: application/json"

const response = await fetch("https://app.example.com/api/v1/projects", {
  headers: {
    Authorization: `Bearer ${process.env.KORDIA_API_KEY}`,
    Accept: "application/json"
  }
})

const body = await response.json()

import os
import requests

response = requests.get(
    "https://app.example.com/api/v1/projects",
    headers={"Authorization": f"Bearer {os.environ['KORDIA_API_KEY']}"},
)

body = response.json()

Req.get!(
  "https://app.example.com/api/v1/projects",
  headers: [authorization: "Bearer #{System.fetch_env!("KORDIA_API_KEY")}"]
).body

Seguridad operacional

  • Guarda la clave como secreto, no en código.
  • Usa una clave por integración.
  • Revoca claves que ya no se usen.
  • Rota claves si sospechas exposición.