Claves de API
Las credenciales que usan tus servidores, qué pasa cuando rotas una y cómo ver lo que ha estado haciendo una clave
Una clave de API es la forma en que tu backend demuestra que eres tú. Las claves de prueba funcionan contra el entorno sandbox; las claves en vivo procesan solicitantes reales. Una clave pertenece a un solo entorno y no se puede usar en el otro.
Esta página es para propietarios y desarrolladores. Si tu equipo no tiene ingenieros, probablemente nunca la abras.
Crear una
Ponle a la clave un nombre que diga para qué se va a usar, confirma con un código de tu app de autenticación y el secreto se muestra una vez.
Una vez significa una vez
El secreto se muestra una sola vez, al crearla. No guardamos ninguna copia que podamos volver a enseñarte. Llévalo directamente al lugar donde tu aplicación guarda sus secretos. Si se pierde, rota la clave y despliega la nueva.
En la vista combinada Todos los entornos, el cuadro de diálogo te obliga a elegir a qué entorno pertenece la clave, porque no hay nada de lo que deducirlo.
Lectura y escritura, o solo lectura
El cuadro de diálogo de creación también pregunta qué puede hacer la clave. Lectura y escritura es la opción predeterminada y es lo que son todas las claves que ya tienes. Solo lectura crea una clave a la que se le rechaza toda escritura, tenga los permisos que tenga, durante toda la vida de la clave.
Solo lectura no dice nada sobre cuánto puede leer una clave. Esa es la siguiente pregunta del cuadro de diálogo, y las dos son independientes: una clave de solo lectura puede limitarse a los resultados, y una clave de lectura y escritura puede leerlo todo.
Usa solo lectura para todo lo que mira tus datos sin cambiarlos: un informe, un panel interno, una exportación nocturna a tus propios sistemas, una herramienta que tu equipo de soporte usa para buscar clientes. Dásela a un contratista que esté construyendo una integración y no podrá decidir un caso ni cambiar un ajuste por accidente.
Esto no se puede cambiar después
Solo lectura es fijo durante toda la vida de la clave. No hay forma de ampliarla después, y es deliberado: una clave de solo lectura que pudieras cambiar no sería una clave que pudieras entregar y olvidarte de ella. Si necesitas que escriba, crea una clave nueva y revoca la antigua.
Las claves de solo lectura están marcadas como tales en la lista, para que veas de un vistazo cuáles de tus credenciales pueden cambiar algo. Las claves de lectura y escritura no llevan ninguna marca, porque son el caso habitual.
Qué puede leer esta clave
La tercera pregunta del cuadro de diálogo de creación decide cuánto de una verificación puede ver la clave.
Solo resultados es la opción predeterminada y es lo que son todas las claves que ya tienes. Lee el estado, el veredicto, los códigos de motivo y el resultado de cada comprobación individual. No puede leer a la persona: ni nombre, ni fecha de nacimiento, ni número de documento, ni imágenes.
Datos completos añade todo eso. La identidad que leímos del documento, incluida la grafía en su
escritura original y las fechas exactamente como las imprime el documento, y las imágenes capturadas
del documento y del selfie. Tu integración la pide en cada llamada, con include=applicant,documents en
una verificación, así que una clave que la tiene sigue devolviendo el resultado sencillo salvo que pidas
más.
Elige datos completos cuando algo tuyo necesite a la persona y no solo la respuesta: una ficha de cliente en tu propia herramienta de soporte, una sincronización nocturna con tus sistemas, un expediente de cumplimiento. Combínala con solo lectura y ese sistema podrá verlo todo sin cambiar nada.
Los permisos se fijan al crearla
Una clave no puede obtener datos completos más adelante, y rotar una clave conserva los permisos que ya
tenía. Si una clave devuelve 403 cuando tu integración pide datos del solicitante, se creó como solo
resultados y la solución es una clave nueva, no una rotación. Crea una, cámbiala y revoca la antigua
cuando nada la esté usando.
Las claves con datos completos están marcadas como Identidad en la lista, para que veas de un vistazo cuáles de tus credenciales pueden leer a una persona real.
Claves que emitimos por ti
Hay una cosa a la que puede llegar una clave que sigue sin concederse nunca por defecto y que no se puede añadir a una clave que crees tú. Pídenosla y la emitimos en tu cuenta, donde aparece en esta lista como cualquier otra.
Back office marca una clave que puede abrir una sesión actuando como una de tus propias personas, que es en lo que se basa conectar tu propio panel de administración. La clave abre la puerta; lo que la persona al otro lado puede hacer realmente lo decide su puesto en la página Equipo, y nada de la clave. Combínala con solo lectura y sus agentes podrán trabajar tu cola sin poder decidir nada.
Una clave de back office necesita puestos asociados
Cada intercambio nombra a una persona, por el id que tú usas para ella, y lo resolvemos con el id
de back office configurado en el propio puesto de esa persona en la página Equipo. Asociar a un
compañero no autoriza una solicitud que nombre a otro: cada persona como la que actúe tu panel necesita
su propio puesto asociado, y un id sin asociar se rechaza con NO_SEAT_FOR_EXTERNAL_ID aunque la
clave en sí se autentique perfectamente. Parece una credencial rota y no lo es.
Rotar y revocar
Rotar emite un secreto nuevo para la misma clave. Revocar anula la clave de inmediato, y cualquier integración que todavía la use empieza a fallar en la siguiente llamada. Ninguna de las dos acciones se puede deshacer, y ambas piden primero tu código de autenticación, porque una clave es acceso a producción en una cadena de texto.
La confirmación de una clave en vivo lo dice con todas las letras. Léela antes de aceptar.
Última vez usada, y qué ha estado haciendo una clave
La lista muestra cuándo se usó cada clave por última vez, que es la llamada a la API más reciente que tenemos registrada para ella en el entorno que estás viendo. Las llamadas de una clave en vivo se registran en En vivo, así que si la columna parece vacía, revisa el selector de entorno antes de concluir que la clave está inactiva.
Selecciona una clave y un panel muestra su tráfico reciente. Se obtiene de los registros de integración, así que un rol sin acceso a Registros ve la clave pero no su historial, y el panel lo indica en lugar de mostrar un gráfico vacío.
Si una clave no hizo ninguna llamada, el panel también lo dice. Cada llamada autenticada que tu backend firma con ella aparece en cuestión de segundos.
Buenas prácticas de mantenimiento
Da a cada integración su propia clave en lugar de compartir una, para que revocar una credencial filtrada no tumbe todo lo que tienes en marcha. Ponles a las claves el nombre del sistema que las guarda. Y recuerda que crear una clave no la suscribe a nada: las verificaciones creadas con una clave nueva solo llegan a tus endpoints si un endpoint de webhook está configurado para recibirlas, algo sobre lo que la página de webhooks te avisa directamente.