Saltar al contenido
Verificada

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.

Verificación de identidad

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_id de 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: true es 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 clearance es public siempre 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 de api_module son solo de sesión

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.

cURL
curl -s https://xuda.ai/cpi/get_account_projects \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY"}'

Por MCP, la misma clave va en cambio en una cabecera Authorization: Bearer; no hay campo api_key. Consulta MCP.

claude mcp add
claude mcp add --transport http xuda https://xuda.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
Mantenla en el servidor

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.

Siguiente