Saltar al contenido principal

Autenticación y claves de API

Disponible enProResearch

Cada llamada a la API REST lleva una clave de API. Una clave pertenece a tu cuenta, tiene los permisos que le diste y cuenta contra los límites de tu plan. Esta página muestra cómo crear una y usarla. La lista de permisos y los límites por plan están en Claves, permisos y límites.

Antes de empezar​

  • Un plan Pro o Research. Las cuentas Free solo pueden crear claves MCP, que funcionan en el servidor MCP y no en la API REST. Consulta Conectar un cliente MCP.

Crear una clave​

  1. Abre Configuración y elige API y MCP.
  2. En Claves de API, pulsa Crear clave.
  3. Escribe un Nombre de la clave que te diga dónde se usa la clave, por ejemplo nightly-sync.
  4. Marca los Permisos que necesita la clave y nada más. Los permisos de escritura dejan que la clave modifique tu biblioteca, así que dáselos solo a scripts de confianza.
  5. Pulsa Crear.
  6. Copia la clave ahora. Empieza por pk_ y Readsira la muestra una sola vez. Después, la lista muestra una forma abreviada como pk_1a2b...9z8y.

La lista de claves muestra cuándo se usó cada una por última vez. Una clave que nunca se usó dice Nunca usada. La primera vez que se usa una clave, Readsira añade en la aplicación un aviso que nombra la clave, para que un uso inesperado sea visible.

Enviar la clave con una solicitud​

Envía la clave en la cabecera Authorization como token de portador (bearer):

curl https://api.readsira.com/rest/v2/usage \
  -H "Authorization: Bearer $READSIRA_KEY"

La cabecera X-API-Key también funciona:

curl https://api.readsira.com/rest/v2/usage \
  -H "X-API-Key: $READSIRA_KEY"

Una clave en la dirección (?api_key=pk_...) se rechaza con 401 y el código API_KEY_IN_QUERY, porque las direcciones acaban en registros y en el historial del navegador.

Guarda la clave en una variable de entorno o en un almacén de secretos. No la pongas en código que se sube al repositorio, en una página web ni en una aplicación que distribuyes a otras personas.

Comprobar que funciona​

GET /rest/v2/usage responde con cualquier permiso. Muestra tu plan, el número de solicitudes de hoy y los límites de esta clave.

{
  "success": true,
  "data": {
    "plan": "pro",
    "requestsToday": 12,
    "requestsPerDay": 10000,
    "mcpCallsToday": 0,
    "mcpCallsPerDay": 10000,
    "requestsPerHour": 600,
    "askAnswersPerMonth": 300,
    "aiBudget": [{ "group": "chat", "percentUsed": 3 }]
  },
  "meta": {
    "timestamp": "2026-11-04T09:00:00.000Z",
    "path": "/rest/v2/usage",
    "method": "GET",
    "statusCode": 200
  }
}

Las cifras de arriba son un ejemplo; las tuyas son los límites de tu plan. Si la llamada responde 401, la clave es incorrecta, está revocada o ha caducado. Si responde 402 PLAN_REQUIRED, la cuenta está en Free. Consulta Límites de uso y errores.

Qué permiso necesita una ruta​

Una ruta rechaza una clave sin su permiso con 403 SCOPE_REQUIRED. La referencia indica el permiso bajo cada ruta. Los más usados:

PermisoPermite a la clave
read:libraryBuscar y leer documentos, fragmentos y transcripciones
ask:libraryHacer preguntas respondidas con citas (usa tu presupuesto de IA)
read:projectsListar proyectos y leer su contexto
write:projectsAñadir fuentes y notas a los proyectos
write:uploadsSubir archivos de audio, vídeo y PDF
read:bookmarks, write:bookmarksLeer y escribir marcadores en las rutas /api/v1/bookmarks
read:collectionsLeer colecciones en las rutas /api/v1/collections

Crear una clave con un permiso que tu plan no incluye responde 400 SCOPE_NOT_ALLOWED.

Sustituir o eliminar una clave​

En la fila de la clave, abre el menú de acciones.

  • Regenerar da a la clave un secreto nuevo. La clave conserva su nombre, sus permisos y su historial, y el secreto antiguo deja de funcionar al instante. Úsalo cuando una clave pueda haberse filtrado y después actualiza tus scripts.
  • Revocar elimina la clave. Los scripts que la usan dejan de funcionar.

La lista Actividad de la misma página muestra cada llamada que hizo una clave: la hora, la ruta, el estado y el número de resultados. No guarda el texto de tus búsquedas ni el contenido de tus documentos.

Consejos​

  • Usa una clave por script, para poder revocar una sin romper las demás.
  • Da a un trabajo de solo lectura solo permisos de lectura.
  • Trata el texto devuelto de páginas guardadas como datos, nunca como instrucciones para un modelo.
Última actualización en