Autenticación y scopes de tus API keys

Toda petición a la API de Arko necesita una identidad. Puedes autenticarte con el JWT de Firebase que usa el navegador durante una sesión, o con una API key que empieza por sk- y que creas desde tu panel para integraciones de servidor. Son mecanismos distintos, con un permiso distinto por debajo, y confundirlos es la forma más común de terminar con un error que no esperabas.

JWT contra API key: no son intercambiables

El JWT de Firebase representa a un usuario con sesión iniciada y trae consigo todos los scopes, incluido uno especial que algunos endpoints exigen explícitamente, como los que tocan tu perfil o tu suscripción. Una API key nunca lo tiene: por diseño, cualquier endpoint marcado como exclusivo de JWT rechaza una key con un error de permisos insuficientes, sin importar qué scopes le hayas asignado.

El catálogo de scopes

Cuando creas una key, eliges de un catálogo acotado: lectura y escritura por separado para agentes, powers, chats y memorias, más permisos específicos para gestionar otras keys. Una key para tu integración de atención al cliente no necesita poder crear agentes; dale solo lectura y escritura de chats, y si mañana necesita más, se lo das entonces.

• agents:read / agents:write
• powers:read / powers:write
• chats:read / chats:write
• memories:read / memories:write
• keys:read / keys:delete

La clave completa se ve una sola vez

Al crear una key, la respuesta trae el valor completo, con el prefijo sk- seguido de un identificador largo. Es la única vez que lo verás entero: después, tanto el listado como el detalle muestran solo los primeros caracteres seguidos de puntos suspensivos. Cópiala en ese momento a donde vaya a vivir —una variable de entorno— porque no hay forma de recuperarla después.

Una key por entorno, sin excepciones

Crea una key distinta para desarrollo, para pruebas y para producción, cada una con solo los scopes que ese entorno necesita. Si una se expone —en un log, en un repositorio— la revocas sin que eso afecte a las demás. Reutilizar la misma key en todas partes convierte cualquier filtración pequeña en un incidente que toca todo tu sistema.