Autenticación de la API
Autentica solicitudes a la API de Rivya con claves Bearer, permisos por ámbito, visualización única del secreto, revocación y rotación.
Última revisión el 5 de noviembre de 2026
Rivya API usa claves API para acceso de servidor a servidor.
Una clave API no es lo mismo que una sesión de navegador. No uses cookies, estado de sesión de Better Auth ni un token personal del navegador como credencial de API pública.
Formato del header
Envía la clave en el header Authorization:
Authorization: Bearer rvya_sk_...La clave completa solo se muestra una vez al crearla. Rivya guarda un hash y un prefijo visible, no el secreto completo.
Crear una clave
Inicia sesión en Rivya.
Abre ajustes de API Keys.
Introduce un nombre de 1 a 80 caracteres y crea la clave. Los ajustes conceden todos los permisos siguientes, sin selector.
Copia la clave completa inmediatamente.
Guárdala en un gestor de secretos del servidor o en una variable de entorno.
No pongas la clave en JavaScript del cliente, bundles de apps móviles, repos públicos, eventos de analytics ni logs.
Scopes actuales
Las claves nuevas de los ajustes reciben los nueve permisos siguientes. No se puede elegir un subconjunto ni editar los permisos de una clave existente.
models:read— Incluido en las claves nuevas; la lista de modelos es pública y no comprueba este permiso.generations:create— Envía generaciones a modelos disponibles.generations:read— Lee y actualiza generaciones de la cuenta propietaria.files:create— Sube referencias admitidas para la cuenta propietaria.files:read— Lee metadatos de archivos disponibles de la cuenta propietaria.credits:read— Lee el saldo actual de la cuenta.webhooks:manage— Gestiona endpoints, secretos de firma y entregas; también requiere webhooks habilitados.chat:create— Envía solicitudes normales o streams a modelos de Chat admitidos.chat:read— Lista sesiones creadas por API y lee mensajes confirmados de la cuenta propietaria.
La clave usa los créditos y recursos de la cuenta que la creó, sin acceso a tareas, archivos ni sesiones ajenos. Si una clave antigua carece de permisos para archivos, Chat o webhooks, crea otra y actualiza el servidor; los ajustes no añaden permisos a la clave antigua.
Caducidad de la clave
Las claves creadas en los ajustes no caducan automáticamente y el formulario no permite fijar una fecha de caducidad. Si una clave tiene una caducidad configurada, las solicitudes protegidas devuelven api_key_expired desde ese momento.
La clave también deja de autorizar solicitudes al revocarse o bloquearse la cuenta propietaria. Tener permisos válidos no activa una función de API deshabilitada.
Revocar y rotar
Revocar rechaza solicitudes protegidas posteriores, pero no cancela generaciones aceptadas. En una rotación planificada, crea y guarda la nueva clave, actualiza el servidor, comprueba con GET /api/v1/credits y después revoca la antigua. Los ajustes crean y revocan, sin sustitución directa. Consultar el saldo correctamente solo verifica autenticación y credits:read, no acceso a generación, archivos, Chat ni webhooks. Si hay exposición, revoca primero y sigue estos pasos.
Si una clave queda expuesta:
Revoca la clave expuesta en los ajustes de claves API.
Crea una clave nueva.
Actualiza el secreto del servidor.
Confirma que la nueva clave funciona con
GET /api/v1/credits.Elimina la clave antigua de sistemas de build, logs y variables de despliegue.
Las claves revocadas devuelven api_key_revoked.
Errores de autenticación
Los endpoints protegidos devuelven error con code, message y, cuando existe, requestId. Los códigos 401 son: api_key_missing si falta un Bearer válido; api_key_invalid si formato, prefijo o secreto no corresponden a una cuenta; api_key_revoked si se revocó la clave o se bloqueó la cuenta; api_key_expired al llegar a su vencimiento. api_scope_denied (403) requiere el permiso correcto: sustituye la clave antigua, pues no se editan sus permisos en ajustes. public_api_disabled (503) indica API deshabilitada o configuración hash no disponible; también se usa si la función independiente de webhooks está apagada. Otra clave no activa la función.
Errores comunes de autenticación:
api_key_missingapi_key_invalidapi_key_revokedapi_key_expiredapi_scope_deniedpublic_api_disabled
Consulta errores y límites de la API para ver la tabla completa de errores públicos.
