Claves de API

Gestiona claves de API propias de un equipo, mediante programación o desde el panel. Las claves se autentican con el encabezado Authorization: Bearer.

Crear una clave

Genera una nueva clave para un equipo y un entorno. La respuesta incluye el secreto en texto plano — guárdalo de inmediato, ya que no podrá recuperarse de nuevo.

curl -X POST https://api.seeitlive.io/v1/keys \
  -H "Authorization: Bearer <dashboard-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "teamId": "<uuid>", "name": "Server key", "env": "live", "embedOrigins": ["https://acme.odoo.com"] }'

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "Server key",
  "env": "live",
  "prefix": "sil_live_ab12cd",
  "secret": "sil_live_ab12cdxxxxxxxxxxxxxxxxxxxxxxxx"
}

Listar claves

Devuelve las claves activas (no revocadas) de un equipo. El secreto nunca se incluye — solo el prefijo, suficiente para identificar una clave en el panel o en los registros.

[
  {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "Server key",
    "env": "live",
    "prefix": "sil_live_ab12cd",
    "embedOrigins": ["https://acme.odoo.com"],
    "lastUsedAt": "2026-07-01T12:03:44.000Z",
    "createdAt": "2026-06-15T09:12:00.000Z"
  }
]

Actualizar una clave

Actualiza parcialmente una clave. Solo se modifican los campos incluidos; los campos omitidos permanecen sin cambios.

curl -X PATCH https://api.seeitlive.io/v1/keys/d290f1ee-6c54-4b01-90e6-d701748f0851 \
  -H "Authorization: Bearer <dashboard-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "allowedIps": ["10.0.0.0/8 # office VPN"], "embedOrigins": ["https://acme.odoo.com # crm"], "expiresAt": "2026-12-31T00:00:00.000Z" }'

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "Server key",
  "env": "live",
  "prefix": "sil_live_ab12cd",
  "allowedIps": ["10.0.0.0/8 # office VPN"],
  "embedOrigins": ["https://acme.odoo.com # crm"],
  "expiresAt": "2026-12-31T00:00:00.000Z",
  "lastUsedAt": "2026-07-01T12:03:44.000Z",
  "createdAt": "2026-06-15T09:12:00.000Z"
}

Rotar una clave

Emite un secreto nuevo para una clave existente e invalida el anterior de inmediato. La clave conserva su identificador, nombre, entorno y ajustes: las listas de origen permitidas, la firma y el TOTP sobreviven a la rotación. El secreto en texto plano se muestra una sola vez, igual que al crearla.

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "Server key",
  "env": "live",
  "prefix": "sil_live_ef34gh",
  "secret": "sil_live_ef34ghxxxxxxxxxxxxxxxxxxxxxxxx"
}

Definir la clave predeterminada

Marca una clave como la predeterminada del equipo. El panel la usa cuando se crea una sesión desde la interfaz, de modo que esas sesiones caen en el entorno de esa clave y se le atribuyen. Definir una nueva predeterminada anula la anterior; una clave revocada no puede serlo.

{ "ok": true }

Revocar una clave

Desactiva la clave de inmediato. Las solicitudes en curso que la usen empiezan a fallar de inmediato, y deja de aparecer en la respuesta de la lista.

{ "ok": true }

Firma de solicitudes

La firma añade una verificación HMAC además de la clave de portador. Consulta el contrato de firma en la guía de autenticación para saber exactamente cómo calcular y enviar la firma.

Activar la firma

Activa la firma para una clave y devuelve el secreto de firma. El secreto se muestra una sola vez — guárdalo de inmediato.

{ "signingSecret": "3fa1e2d0c9b84a5b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7081920a3b4c5" }

Rotar el secreto de firma

Emite un nuevo secreto de firma para una clave, invalidando el anterior. También se muestra una sola vez.

{ "signingSecret": "8c9d0e1f2a3b4c5d6e7f8091a2b3c4d53fa1e2d0c9b84a5b6e7f8091920a3b4c" }

Desactivar la firma

Desactiva la firma para una clave. Las solicitudes hacia ella ya no necesitan firma.

{ "ok": true }

TOTP por clave

Un segundo factor opcional, propio de una clave: una vez activado, cada petición hecha con ella debe llevar además un código rotatorio válido en una cabecera X-SeeItLive-Totp. Útil para una clave en manos de una persona y no de un servidor.

Activar

Devuelve la semilla y una URL otpauth para una aplicación de autenticación. Ambas se muestran una sola vez: la semilla no vuelve a ser legible.

{
  "secret": "JBSWY3DPEHPK3PXP",
  "otpauthUrl": "otpauth://totp/SeeItLive:key%3Asil_live_ab12cd?secret=JBSWY3DPEHPK3PXP&issuer=SeeItLive"
}

A partir de ahí, las peticiones con esa clave deben incluir el código de 6 dígitos del momento; sin él fallan con un 401.

curl https://api.seeitlive.io/v1/sessions/<id>/status \
  -H "Authorization: Bearer sil_live_ab12cdxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-SeeItLive-Totp: 418205"

Desactivar

Apaga el segundo factor y descarta la semilla. Las peticiones con la clave dejan de exigir un código.

{ "ok": true }

Anclaje de certificado de cliente (mTLS)

Ancla una clave a un único certificado de cliente. Una vez anclada, una petición solo se acepta si tu punto de entrada reenvía el certificado de quien llama como PEM codificado para URL en una cabecera X-Ssl-Client-Cert y su huella SHA-256 coincide con la anclada.

Anclar un certificado

Envía el certificado en PEM dentro de un campo pem. La respuesta devuelve la huella SHA-256 que se exigirá.

curl -X POST https://api.seeitlive.io/v1/keys/d290f1ee-6c54-4b01-90e6-d701748f0851/cert/upload \
  -H "Authorization: Bearer <dashboard-jwt>" \
  -H "Content-Type: application/json" \
  -d "{ \"pem\": \"$(awk '{printf "%s\\n", $0}' client.crt)\" }"

{
  "fingerprint": "9f:86:d0:81:88:4c:7d:65:9a:2f:ea:a0:c5:5a:d0:15:a3:bf:4f:1b:2b:0b:82:2c:d1:5d:6c:15:b0:f0:0a:08"
}

Quitar el anclaje

Elimina el certificado anclado y deja de exigirlo.

{ "ok": true }

Restricciones de funciones

Un equipo puede limitar lo que cada clave puede hacer, por debajo de lo que incluye su plan. Tres funciones del plan se pueden ajustar por clave: sms, annotations y snapshot_history. Una clave hereda el valor predeterminado del equipo para cada función, salvo que lo anule. Nombrar una función ajustable que el plan no incluye devuelve 402; cualquier campo distinto de estas tres funciones devuelve 400.

Valores predeterminados del equipo

Cada campo es opcional y acepta true o false; una función que nunca se ajustó está activada. Requiere el permiso de gestión de claves.

Anulaciones por clave

true o false anula el valor predeterminado del equipo; null elimina la anulación para que la clave lo herede de nuevo. effective es lo que obtienen las solicitudes hechas con la clave. Requiere el permiso de gestionar claves, y la clave debe estar activa (no revocada).

{ "sms": false, "annotations": null }

{
  "features": [
    { "key": "sms", "planAllows": true, "teamDefault": true, "override": false, "effective": false },
    { "key": "annotations", "planAllows": true, "teamDefault": false, "override": null, "effective": false },
    { "key": "snapshot_history", "planAllows": false, "teamDefault": true, "override": null, "effective": false }
  ]
}

Registro de accesos

Cada intento de acceso hecho con una clave queda registrado — tanto los aciertos como los fallos — del más reciente al más antiguo. Leerlo exige el permiso de gestión de claves. El registro no guarda secretos: ni la clave, ni el cuerpo de las peticiones.

{
  "items": [
    {
      "id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
      "outcome": "failure",
      "failureReason": "source_not_allowed",
      "ip": "203.0.113.7",
      "userAgent": "curl/8.5.0",
      "method": "POST",
      "path": "/api/v1/sessions",
      "createdAt": "2026-07-01T12:03:44.000Z"
    },
    {
      "id": "1f2a3b4c-5d6e-7f80-91a2-b3c4d5e6f708",
      "outcome": "success",
      "failureReason": null,
      "ip": "198.51.100.24",
      "userAgent": "@seeitlive/sdk 0.1.0",
      "method": "GET",
      "path": "/api/v1/sessions/abc/status",
      "createdAt": "2026-07-01T12:02:10.000Z"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA3LTAxVDEyOjAyOjEwLjAwMFoiLCJpZCI6IjFmMmEzYjRjIn0"
}

outcome es success o failure. En un fallo, failureReason toma uno de estos valores: invalid_key, revoked, expired, source_not_allowed, totp, client_cert, signature, env_mismatch o malformed.