Crea claves de API en Desarrolladores → Claves de API, una por servicio con el acceso que necesita. Guárdalas en el servidor, rótalas y resuelve 401 y 403.
Desarrolladores → Claves de API, delimitado a la aplicación que tengas seleccionada. Cada aplicación tiene una clave Principal, y puedes crear más, una por servicio, cada una con su propio acceso y su propia caducidad. Una clave es un secreto de servidor: nunca en código de frontend ni en el paquete de una app.
Tus claves de API están en Desarrolladores → Claves de API dentro de la consola, delimitadas a la aplicación en la que estés trabajando. Trata cada clave como una contraseña: otorga acceso a la API en nombre de esa aplicación.
#Encontrar tu clave
- Inicia sesión en la Consola de Negocio
Ve a business.didit.me e inicia sesión.
- Selecciona tu aplicación
Elige la aplicación en la tarjeta de aplicación de la parte superior de la barra lateral. Cada aplicación tiene sus propias claves.
- Abre Desarrolladores y después Claves de API
La pestaña Claves muestra todas las claves, empezando por la clave Principal, con su acceso, cuándo se usó por última vez y cuándo caduca.
#Crear una clave
Da a cada servicio que llama a Didit su propia clave, para que puedas ver lo que hace cada uno y revocarla por separado.
- Pulsa Crear clave
En Desarrolladores → Claves de API.
- Ponle un nombre y elige el entorno
Nombra la clave según el servicio que la va a usar, elige Producción (verificaciones reales, facturadas) o Sandbox (datos de prueba, nunca facturados; la clave se crea en la aplicación Sandbox de tu organización), y elige cuándo caduca: nunca, a los 30 días, a los 90 días o al año, o en una fecha que elijas.
- Elige su acceso
Acceso total lee y escribe todo, para tu propio backend. Solo lectura ve sesiones, decisiones y medios, pero no puede cambiar nada, para un socio que solo necesita resultados. Personalizado te permite elegir, recurso por recurso. Desmarca Incluir medios cuando el servicio solo necesite la decisión, no las imágenes de documentos, selfies, vídeos ni informes en PDF.
- Revisa y copia el secreto
El secreto completo se muestra una sola vez, cuando se crea la clave. Cópialo directamente en tu gestor de secretos.
La clave Principal es el secreto original de la aplicación. Siempre tiene acceso total y se puede rotar, pero no revocar.
#La clave de API y el secreto de firma son cosas distintas
Merece la pena decirlo con claridad, porque confundirlos produce errores confusos:
| Para qué sirve | Dónde | |
|---|---|---|
| Clave de API | Autenticar tus llamadas a Didit, en la cabecera x-api-key | Por aplicación, tantas como necesites |
| Secreto de firma del webhook | Verificar que un webhook entrante realmente vino de Didit | Por endpoint de webhook |
Enviar el secreto de firma como si fuera tu clave de API produce un 401. Verificar un webhook con tu clave de API produce un desajuste de firma. Ambos son errores habituales.
Tu clave de API es un secreto. Nunca la pongas en código de frontend, en un repositorio público ni en el paquete de una app móvil - guárdala solo en el servidor. Una clave dentro del paquete de una app publicada es una clave que ya tiene un atacante. Consulta autenticación de la API.
#Conseguir una clave para pruebas
No pruebes contra producción. Cambia la consola a Sandbox y crea una clave ahí, o elige Sandbox como entorno al crearla. Las sesiones de sandbox simulan cada comprobación externa, nunca se facturan y no tocan datos reales de usuarios.
Una clave pertenece a una aplicación y, con ella, al entorno de esa aplicación: una clave de sandbox nunca crea una verificación de producción, y una clave de producción nunca crea una de sandbox. Merece la pena nombrar tus claves sin ambigüedad en el lugar donde guardes tus secretos. Consulta pruebas en sandbox.
#Rotar tu clave
Si una clave puede haberse expuesto, ábrela y elige Rotar clave. Obtienes un secreto nuevo, y el anterior sigue funcionando durante 24 horas, para que puedas desplegar el secreto nuevo sin tiempo de inactividad. Después, toda solicitud con el secreto anterior devuelve un 401.
Si una clave tiene que dejar de funcionar ya, usa Revocar clave en su lugar. Revocarla la detiene al instante y no se puede deshacer. La clave Principal solo se puede rotar.
Rotar las claves según un calendario es una buena práctica. Planifícalo como un despliegue, no como un clic.
#Solucionar los errores 401 y 403
| Error | Causa | Solución |
|---|---|---|
401 | La clave falta, está mal formada, ha caducado, se ha revocado o se rotó hace más de 24 horas | Revisa la clave en Desarrolladores → Claves de API para esa aplicación. Busca espacios en blanco o comillas sueltas, y comprueba que no hayas pegado un secreto de firma |
403 | La clave es válida pero esta llamada no está permitida | Suele ser la aplicación equivocada, un campo exclusivo de sandbox en una clave de producción (o al revés), un acceso que no se le dio a la clave (por ejemplo, una clave de solo lectura que intenta escribir), o una función no habilitada en tu cuenta |
Un 403 en un flujo de trabajo concreto casi siempre significa que la clave pertenece a una aplicación distinta de la que es propietaria de ese flujo de trabajo. Cambia de aplicación en la consola y usa una de sus claves en su lugar. Desglose completo: errores de la API y qué significan.
#Restringir lo que puede hacer una clave
Elige el acceso al crear la clave y cámbialo más adelante con Editar acceso (el secreto sigue siendo el mismo; el acceso de la clave Principal no se puede editar). Solo lectura impide que un socio cambie nada, Personalizado establece Ninguno, Lectura o Escritura por recurso (sesiones, decisiones, medios, personas, empresas y más), y dejar Incluir medios desactivado impide que un servicio descargue imágenes de documentos, selfies, vídeos e informes en PDF. En Límites, una clave también puede restringirse a algunos flujos de trabajo, solo a sesiones aprobadas o a una lista de direcciones IP: una solicitud desde fuera de la lista responde 403, y una sesión fuera de los flujos de trabajo o estados de la clave responde 404. Abre una clave para ver exactamente lo que puede hacer; una clave nunca puede hacer más de lo que su acceso permite.
#Quién de tu equipo puede ver las claves
La visibilidad de las claves sigue el rol: ver la página requiere permiso para leer claves de API, que el rol Desarrollador incluye. Los secretos permanecen enmascarados en la consola. Si un compañero de equipo no encuentra la página, comprueba su rol antes de reportarlo. Consulta invitar a miembros del equipo y asignar roles.
#Cada llamada queda registrada
Las solicitudes con clave de API aparecen en el Registro de auditoría atribuidas a la clave en lugar de a una persona. Esa es exactamente la razón por la que una clave compartida entre varios servicios hace un incidente más difícil de investigar: una clave por consumidor es más fácil de razonar. Consulta cómo usar los registros de auditoría.
¿Sigues atascado? Habla con una persona.
Incluye el ID de tu organización y el ID de la sesión sobre la que preguntas.