Gestionar tus claves de API
Encuentra tu clave de API en API y webhooks dentro de la consola, guárdala solo en el servidor, usa una aplicación sandbox separada para las pruebas y soluciona los errores 401 y 403.
API y webhooks, delimitado a la aplicación que tengas seleccionada. Una clave por aplicación, y la clave es el entorno - no existe una clave de prueba separada en una aplicación de producción. Es un secreto de servidor: nunca en código de frontend ni en el paquete de una app.
Tu clave de API vive en API y webhooks, en la barra lateral de la consola, delimitada a la aplicación en la que estés trabajando. Trátala como una contraseña: otorga acceso completo 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 que quieras en el desplegable de la parte superior de la consola. Cada aplicación tiene su propia clave.
- Abre API y webhooks
Tu clave de API está aquí, junto con tus destinos de webhook y sus secretos de firma.
- Create API key emite una clave nueva; las claves son por aplicación.
- El secreto se muestra aquí una sola vez: cópialo en tu propio gestor de secretos.
- Rotate secret sustituye el secreto sin cambiar el nombre de la clave.
- Last used es cómo distingues una clave activa de una olvidada antes de revocarla.
#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 |
| Secreto de firma del webhook | Verificar que un webhook entrante realmente vino de Didit | Por destino |
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. Crea una aplicación separada en modo sandbox - las sesiones de sandbox simulan cada comprobación externa, nunca se facturan y no tocan datos reales de usuarios. Usa su clave mientras desarrollas, y mantén una aplicación de producción separada para las verificaciones reales.
No existe una "clave de prueba" en una aplicación de producción. La clave es el entorno, así que 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, regénerala desde la misma página de API y webhooks. Regenerarla invalida la clave anterior de inmediato, así que actualízala primero en todos los lugares donde se use - de lo contrario, tu tráfico de producción empieza a fallar en el momento en que pulsas el botón.
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 o se ha regenerado | Copia la clave actual desde API y webhooks para esa aplicación. Comprueba que no haya espacios en blanco o comillas sueltas, y 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 permiso que le falta a tu clave, 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 copia su clave en su lugar. Desglose completo: errores de la API y qué significan.
#Restringir lo que puede hacer una clave
Si tu necesidad es limitar a qué categorías de datos puede acceder una clave - por ejemplo, para impedir que un servicio recupere imágenes de documentos - eso es una cuestión de permisos y no un ajuste de la clave, y lo disponible depende de tu cuenta. Pregunta a soporte en lugar de asumir que una clave no tiene restricciones o que sí las tiene; ambas suposiciones son arriesgadas en direcciones opuestas.
#Quién de tu equipo puede ver las claves
La visibilidad de las claves sigue el rol. El rol Desarrollador cubre las claves de API; Lector no. 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 Registros de auditoría atribuidas a la aplicación en lugar de a una persona - que 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.