Referencia para Desarrolladores

Documentación de la API

Integra la firma y verificación de Kernel Security en tu aplicación usando claves API.

Cómo funciona

Firma y verificación, en 30 segundos.

Firma una vez.
Que cualquiera pueda comprobarlo.

Empieza con tu contenido.

La API de Kernel Security permite a tu aplicación firmar archivos multimedia con marcas de agua criptográficas y verificar su firma de forma programática. Todas las solicitudes deben autenticarse con una clave API emitida desde el panel de administración de tu organización.

URL Base

https://api.kernelsecurity.io

Límites de Tasa

Endpoint	Límite	Notas
POST /sign	10 / min	CPU intensivo — cada trabajo puede tardar 30–120 s
POST /verify	60 / min	Síncrono, normalmente < 5 s

Los límites se aplican por clave API. Superar el límite devuelve HTTP 429.

Todas las solicitudes a la API requieren un token Bearer en la cabecera Authorization. Las claves API comienzan con krnl_ y se emiten por organización. El texto plano de la clave solo se muestra una vez al crearla — guárdala de forma segura.

Cabecera de Autorización

Authorization: Bearer krnl_<your-api-key>

Ámbitos

Ámbito	Otorga acceso a
sign	POST /sign — enviar multimedia para firma con marca de agua
verify	POST /verify — enviar multimedia para verificación de marca de agua

Códigos de Error de Autenticación

Estado HTTP	Significado
401	Clave API ausente o inválida
403	La clave no tiene el ámbito requerido, o el author_id pertenece a otra organización
429	Límite de tasa superado — reintenta tras el intervalo indicado en Retry-After

POST/sign

Envía un archivo multimedia para firma criptográfica con marca de agua. El trabajo se encola de forma asíncrona; consulta el endpoint de estado para obtener la URL del archivo firmado. Requiere el ámbito sign.

Solicitud

Content-Type: multipart/form-data

Campo	Tipo	Descripción
file	File	El archivo multimedia a firmar (MP4, MOV, MKV, WebM, MP3, WAV, FLAC, OGG)
certificate_json	string (JSON)	Objeto JSON que describe el certificado de firma (ver esquema a continuación)

Esquema del Certificado

{
  "author_id": "<identity-uuid>",
  "title":     "optional media title",
  "timestamp": "2026-05-04T12:00:00Z"
}

Respuesta

HTTP 202 Accepted

{
  "job_id": "arq:sign:<uuid>"
}

Consulta del Resultado

El trabajo de firma se ejecuta de forma asíncrona. Consulta el endpoint de estado hasta que el estado sea complete o failed.

GET/sign/status/{job_id}

{
  "status":    "complete",
  "video_url": "https://cdn.kernelsecurity.io/...",
  "content_id": "<uuid>"
}

Ejemplo cURL

curl -X POST https://api.kernelsecurity.io/sign \
  -H "Authorization: Bearer krnl_<key>" \
  -F "[email protected]" \
  -F 'certificate_json={"author_id":"<uuid>"}'

POST/verify

Envía un archivo multimedia para comprobar si lleva una marca de agua Kernel válida. Devuelve HTTP 200 para todos los resultados — un veredicto RED es un resultado válido, no un error. Requiere el ámbito verify.

Solicitud

Content-Type: multipart/form-data

Campo	Tipo	Descripción
file	File	El archivo multimedia a verificar (mismos formatos que /sign)

Respuesta

HTTP 200 OK

{
  "verdict":               "GREEN" | "YELLOW" | "RED",
  "content_id":            "<uuid> | null",
  "author_id":             "<uuid> | null",
  "author_name":           "string | null",
  "org_name":              "string | null",
  "red_reason":            "string | null",
  "wid_match":             true | false | null,
  "signature_valid":       true | false | null,
  "n_segments_total":      42,
  "n_segments_decoded":    40,
  "n_erasures":            2,
  "fingerprint_confidence": 0.97,
  "audio_verdict":         "GREEN" | null,
  "video_verdict":         "GREEN" | null
}

Veredictos

Veredicto	Significado
GREEN	Marca de agua Kernel válida: se confirma quién firmó el contenido
YELLOW	Coincidencia parcial — algunos segmentos decodificados, firma no concluyente
RED	Marca de agua ausente o no coincidente: no se puede confirmar quién firmó el contenido

Ejemplo cURL

curl -X POST https://api.kernelsecurity.io/verify \
  -H "Authorization: Bearer krnl_<key>" \
  -F "[email protected]"

Las claves API son gestionadas por los administradores de la organización a través del panel Admin → Claves API o estos endpoints REST. Los cuatro endpoints requieren autenticación JWT de nivel administrador — no pueden llamarse con una clave API.

GET/organizations/{org_id}/api-keys

Lista todas las claves API de la organización (plaintext_key siempre es null en las respuestas de listado).

Parámetros de Consulta

Parámetro	Por defecto	Descripción
page	1	Número de página (índice 1)
page_size	20	Resultados por página (máx. 100)

HTTP 200 OK

{
  "items": [
    {
      "key_id":        "<uuid>",
      "key_prefix":    "krnl_ab12",
      "name":          "Production Key",
      "plaintext_key": null,
      "created_at":    "2026-05-01T00:00:00Z",
      "last_used_at":  "2026-05-04T08:30:00Z",
      "is_active":     true,
      "scopes":        ["sign", "verify"],
      "expires_at":    null
    }
  ],
  "total": 3,
  "page": 1,
  "total_pages": 1
}

POST/organizations/{org_id}/api-keys

Crea una nueva clave API. Todos los campos son opcionales. El texto plano de la clave solo se devuelve en esta respuesta.

{
  "name":       "My Key",
  "scopes":     ["sign", "verify"],
  "expires_at": "2027-01-01T00:00:00Z"
}

⚠ Guarda el plaintext_key inmediatamente — no volverá a mostrarse.

HTTP 201 Created

{
  "key_id":        "<uuid>",
  "key_prefix":    "krnl_ab12",
  "plaintext_key": "krnl_ab12cd34ef56...",
  "scopes":        ["sign", "verify"],
  "expires_at":    "2027-01-01T00:00:00Z",
  "is_active":     true
}

PATCH/organizations/{org_id}/api-keys/{key_id}

Renombra una clave (pasa name: null para borrar el nombre).

{ "name": "Renamed Key" }

DELETE/organizations/{org_id}/api-keys/{key_id}

Revoca permanentemente una clave. La clave se desactivará y no podrá reactivarse.

HTTP 204 No Content

Endpoint

Límite

Notas

POST /sign

10 / min

CPU intensivo — cada trabajo puede tardar 30–120 s

POST /verify

60 / min

Síncrono, normalmente < 5 s