Autenticación
Claves de API de cuenta, acceso total frente a personalizado y dónde crear una.
Cada llamada a CPI lleva una clave de API. No hay un id de cliente aparte, ni un protocolo OAuth, ni una firma que calcular: una sola clave, enviada con la solicitud.
Crear una clave
Las claves viven en el panel, en la pantalla Desarrolladores del menú de la cuenta, en su pestaña API keys.
Un proyecto tiene su propia pestaña API que crea el mismo tipo de clave ya limitada a ese
proyecto, así que nunca escribes un app_id a mano. El sandbox de la referencia de la API
interactiva también puede crear una al momento, para que pruebes un método antes de conectar nada
a tu propio código.
Crear una clave de API requiere verificación de identidad, la misma comprobación de nivel 2 que Xuda pide antes de entregar un número de teléfono, un buzón o una IP portátil. Una cuenta sin nada verificado ve un aviso para verificar antes de que se abra el formulario de la clave.
Ámbito: como qué cuenta actúa la clave
Una clave se crea con uno de tres ámbitos y siempre actúa sobre la cuenta o la app para la que se creó:
- Cuenta: actúa directamente sobre tu cuenta, como lo harías desde una sesión iniciada en el panel. Llega a todos los métodos a los que puede llegar una clave de cuenta normal.
- App: creada desde la pestaña API de un proyecto, fijada al
app_idde ese proyecto. - Full Stack VPS: se emite automáticamente cuando aprovisionas un Full Stack VPS, limitada a los grupos de capacidades elegidos al crearlo. Consulta Full Stack VPS para ver qué cubre.
Acceso: total o personalizado
Cada clave también elige cuánto de la superficie pública puede alcanzar:
- Acceso total: todo lo que la cuenta puede hacer por la API, incluidos los métodos añadidos después de que
se creara la clave. Los métodos privados quedan excluidos pase lo que pase:
private: truees un muro duro, comprobado en cada llamada, no un valor por defecto que el acceso total anule. - Acceso personalizado: una lista de permitidos explícita que armas marcando métodos en el formulario de la clave, agrupados
por microservicio y con los campos de cada método a la vista. Un método añadido después no se incluye
hasta que vuelvas y lo permitas. Un método cuyo
clearanceespublicsiempre es accesible, incluso con una clave personalizada sin nada marcado, ya que un método público no necesita sesión ni entrada en la lista de permitidos.
Los métodos que crean, actualizan y listan claves de API (create_account_api_key,
get_app_api_keys y el resto de api_module) nunca son accesibles con una clave de API, por diseño:
una credencial no puede crear ni editar credenciales de la cuenta con la que se autentica. Gestiona las claves desde
el panel o desde una sesión iniciada.
Enviar la clave
Por REST normal, la clave es un parámetro más de la solicitud, llamado api_key: un campo del cuerpo JSON
en POST, un parámetro de la cadena de consulta en GET. Consulta
Llamar a un método para ver ambas formas.
Por MCP, la misma clave va en cambio en una cabecera Authorization: Bearer; no hay campo api_key.
Consulta MCP.
Una clave de API es una credencial al portador: quien la tiene actúa como tu cuenta. Nunca la incluyas en código del lado del cliente, ni la subas a un repositorio, ni la pegues en una captura de pantalla compartida. Sustituye una clave de inmediato si alguna vez aparece en alguno de esos lugares; al sustituirla se conservan el nombre y el modo de acceso y se revoca el valor anterior en el mismo paso.