Autenticación y scopes

Cada solicitud a la API pública debe llevar una API key de larga duración como bearer token. Los scopes restringen lo que puede hacer cada clave: concede solo lo que tu integración necesita realmente.

Formato del bearer token

Las API keys tienen este aspecto:

scs_live_t9JQ10cDjddmslzv9mRKYqaDS5ZU1KuDH

El prefijo scs_live_ identifica la clave como credencial de producción para SecureCodingHub. Los tokens tienen 41 caracteres en total (9 caracteres de prefijo + 32 caracteres de cuerpo aleatorio). Se devuelven una única vez al crear la clave.

Envía el token en cada solicitud como un header de autenticación Bearer estándar:

Authorization: Bearer scs_live_t9JQ10cDjddmslzv9mRKYqaDS5ZU1KuDH

Crear una API key

Las API keys se crean en la consola de administración, no a través de la API.

Inicia sesión en app.securecodinghub.com como administrador de la organización.

Abre Organización → Claves de API desde la barra lateral.

Haz clic en + Crear nueva clave. Dale a la clave un nombre descriptivo (por ejemplo, GitHub Actions — CI o Sincronización con Looker BI).

Marca solo los scopes que necesite la integración. Los scopes de solo lectura se resaltan en azul y los de escritura en ámbar.

(Opcional) Establece una fecha de expiración. Las claves sin expiración permanecen válidas hasta que las revoques.

Haz clic en Crear clave. El token completo se muestra en un modal. Cópialo ahora en tu gestor de secretos. No podrás recuperarlo de nuevo: solo se almacenan el prefijo y los últimos cuatro caracteres.

Referencia de scopes

SecureCodingHub usa 16 scopes de grano fino divididos en niveles de lectura y escritura. Una solicitud a un endpoint sin el scope correspondiente devuelve 403 Forbidden con el cuerpo de respuesta {"error":"insufficient_scope","required":"…","present":[…]}.

Scope	Recurso	Nivel	Permite
`org:read`	Organización	Lectura	Leer metadatos de la organización (nombre, plan, asientos).
`users:read`	Usuarios	Lectura	Listar usuarios; obtener detalle de un usuario.
`users:write`	Usuarios	Escritura	Crear, actualizar y desactivar usuarios.
`teams:read`	Equipos	Lectura	Listar equipos y sus miembros.
`teams:write`	Equipos	Escritura	Crear, actualizar y eliminar equipos.
`assignments:read`	Asignaciones	Lectura	Listar asignaciones; obtener detalle con el grado de finalización.
`assignments:write`	Asignaciones	Escritura	Crear, actualizar y desactivar asignaciones.
`custom-courses:read`	Cursos personalizados	Lectura	Listar cursos personalizados con sus elementos.
`custom-courses:write`	Cursos personalizados	Escritura	Crear, actualizar y eliminar cursos personalizados.
`progress:read`	Progreso	Lectura	Progreso de práctica y aprendizaje por usuario.
`certificates:read`	Certificados	Lectura	Listar y descargar certificados.
`audit-log:read`	Registro de auditoría	Lectura	Listar entradas del registro de auditoría.
`compliance:read`	Cumplimiento	Lectura	Datos del panel de cumplimiento.
`content:read`	Contenido	Lectura	Temas, escenarios y mapeo de CWE a temas.
`sarif:ingest`	SARIF	Escritura	Ingerir runs SARIF y asignar formación automáticamente.
`webhook:manage`	Webhooks	Escritura	Gestionar endpoints de webhook salientes.

Conjuntos de scopes recomendados

Caso de uso	Scopes mínimos
Ingesta de SARIF desde CI/CD	`sarif:ingest`
Aprovisionamiento de usuarios desde RR. HH.	`users:write`, `teams:write`
Exportación a BI / informes	`users:read`, `progress:read`, `assignments:read`, `audit-log:read`
Ticketing y SOAR (suscriptores de eventos)	`webhook:manage`, `assignments:read`
Exportación de solo lectura para auditor	`org:read`, `audit-log:read`, `compliance:read`, `certificates:read`

Rotación y revocación

Para rotar una clave, crea primero la sustituta, despliega el nuevo token y luego revoca la antigua en Organización → Claves de API. La revocación es efectiva de inmediato: las solicitudes en curso que usen el token antiguo empezarán a devolver 401 Unauthorized en cuestión de segundos.

Si una clave se filtra, revócala. No existe un estado de "pausa"; la revocación es permanente. El token no puede volver a habilitarse.

Buenas prácticas de almacenamiento

Trata el token como la contraseña de una base de datos. No lo subas nunca al control de código fuente.
Prefiere el almacén de secretos nativo de tu plataforma (AWS Secrets Manager, GCP Secret Manager, GitHub Actions secrets, Vault, 1Password Connect).
En CI, inyecta el token solo en el paso que lo necesita; evita usar echo sobre él.
Emite una clave por integración para poder revocarlas de forma independiente. No compartas una única clave entre CI, BI y SOAR.
Establece una fecha de expiración en los tokens creados para integraciones de corta duración (pruebas de concepto, evaluaciones de proveedores).

Errores comunes

Estado	Respuesta	Significado
`401`	`{"error":"unauthorized"}`	Token ausente, mal formado, revocado o expirado.
`403`	`{"error":"insufficient_scope",…}`	El token es válido pero le falta el scope requerido para este endpoint.
`429`	`{"error":"rate_limited"}`	Se ha alcanzado el límite por minuto o por hora. Consulta Límites de tasa.