Credenciales y Principales

Todo lo que llega al API Gateway trae una credencial. Esta página es sobre qué es realmente una credencial, a quién pertenece, y qué otorga y qué no.

Se administran en API Gateway → API Keys.

El modelo de dos niveles

Praxsuite separa quién llama de qué está sosteniendo.

  Principal  — la identidad        ej. "App Móvil", "Zapier", "Claude MCP"
      |
      +--- Credencial  — una key que prueba que sos eso
      +--- Credencial  — otra, para otro entorno

Un principal es el actor. Tiene un código, un nombre visible, un tipo y un estado.

Una credencial es un secreto emitido a ese principal. Un principal puede tener varias: una por entorno, o una entrando mientras la vieja sale.

Esa separación es lo que hace segura la rotación. Revocar una key filtrada no borra la identidad, no toca sus permisos, y no afecta a ninguna otra key del mismo principal. Emitís un reemplazo y la configuración de la integración — scopes, filtros, permisos de herramientas — queda intacta, porque esa configuración cuelga de la credencial que estás reemplazando, no de un nombre que alguien tenga que volver a tipear.

Tipos de principal

Service es lo que querés para cualquier cosa del lado del servidor. Los principales EndUser no se crean a mano — aparecen cuando una persona se loguea por los endpoints de auth del gateway.

Tipos de key, y dónde va cada una

El prefijo no es decoración. Te dice dónde puede vivir la key.

Una publishable key es pública. Tratala como ya filtrada, porque en un bundle de frontend lo está. Eso no es una falla — es lo que significa "publishable". La protección viene de lo que permiten sus scopes, no de que la key se mantenga secreta. Una key pk_live_ debería poder hacer exactamente lo que un visitante anónimo de tu app puede hacer, y nada más.

Una key sk_live_ es lo contrario: es un secreto al portador, y cualquier cosa que la tenga puede hacer todo lo que sus scopes permitan. Nunca va en un repositorio, en código de cliente, ni en una URL.

El endpoint MCP acepta solo sk_live_. Una publishable key se rechaza ahí, a propósito.

Tipos de credencial

Además de las API keys comunes, el modelo contempla ClientSecret, SignedToken, ClientCertificate, AgentSecret y DeviceSecret para escenarios OAuth y de edge. Para una integración normal, ApiKey es la que querés.

Ciclo de vida

Una credencial siempre está en exactamente un estado:

Cualquier cosa que no sea Active responde 403 FORBIDDEN. Lo mismo si el principal no está activo — suspender una identidad apaga todas sus keys de una, que es la palanca rápida cuando todavía no sabés cuál se filtró.

Una key nueva se muestra exactamente una vez. Solo se guarda un hash de una vía, así que nada en la plataforma puede volver a mostrártela. Si se pierde, emitís una nueva y revocás la vieja — no hay recuperación, por diseño.

Vale la pena setear ExpiresAt incluso sin plan de rotación. Un vencimiento convierte "nos olvidamos de esa integración" en una caída que notás, en vez de una key que sobrevive al proyecto que la creó.

El gateway registra LastUsedAt y LastUsedIp por credencial. Ese es el campo a mirar antes de revocar algo que nadie recuerda haber creado.

Los tres ejes de permisos

Una credencial lleva tres conjuntos de permisos independientes. Están separados porque protegen cosas distintas.

Ninguno puede ampliar lo que otro niega. Otorgar el grupo de herramientas Docs no otorga acceso a un documento que los Docs scopes excluyen; permitir una tabla no habilita una herramienta que está apagada. Un request tiene que pasar todos los ejes que toca.

La consecuencia práctica al depurar un 403: revisá el eje que corresponde a la operación, no el que corresponde al dato. Una llamada MCP que no puede leer una tabla puede estar bloqueada por el scope de tabla o por el grupo de herramientas, y los dos se configuran en lugares distintos.

Caché de respuestas

Una credencial puede cachear sus propias respuestas de consulta:

Los defaults son 60 segundos y 500 entradas.

WriteInvalidated es el interesante: te da un caché que no puede servir datos viejos después de una escritura que hizo tu workspace. Su punto ciego son los datos cambiados por algo que el gateway no vio, y para eso existe Hybrid.

El caché es por credencial, así que una key pública con mucha lectura puede cachear agresivamente mientras tu key de backend no cachea nada.

URLs de archivos

FileUrlMode decide cómo vuelven las columnas File e Image en los resultados:

Proxy mantiene todo acceso a archivo detrás del mismo chequeo de permisos que la fila de la que salió. SasUrl cambia eso por URLs que un navegador puede cargar sin credenciales, que es lo que necesitás para una galería pública — y exactamente lo que no querés para documentos privados, porque cualquiera con la URL puede abrirla hasta que venza.

FileSasExpiryMinutes viene en 60, con piso de 5 minutos y techo de 7 días. Mantenelo corto: el vencimiento es lo único que limita una URL una vez que salió de tu página.

Recomendaciones prácticas

• Una credencial por integración. Las keys compartidas vuelven inútil el log de auditoría y convierten una rotación en una caída coordinada.

• Dale el scope de lo que la integración hace hoy. Un scope es trivial de ampliar después e imposible de des-filtrar.

• Nunca dejes que una key `pk_live_` escriba algo que un visitante no debería poder escribir desde la consola del navegador.

• Poné un vencimiento aunque no tengas plan de rotación.

• Mirá `LastUsedAt` antes de revocar. Es la diferencia entre sacar una key muerta y bajar producción.

Siguiente

• Modelo de Seguridad de PraxQL — cómo se aplica el eje de datos, capa por capa.