Acceso acotado que sigue siendo tuyo

Las conexiones son tokens del espacio de trabajo

Los propietarios y administradores crean conexiones en la página Desarrolladores. Cada conexión es un token de portador ligado a un espacio de trabajo y a una audiencia: los tokens rest (sw_rest_...) solo sirven para /api/v1 y los tokens mcp (sw_mcp_...) solo para /mcp.

Envía el token en la cabecera Authorization. Nunca lo pongas en una URL, una cadena de consulta, un archivo de importación ni en código que llegue al navegador.

Authorization: Bearer sw_rest_...

Los permisos acotan lo que permite tu rol

Una conexión nueva empieza con los permisos de solo lectura: workspaces:read, catalog:read y worlds:read. Añade solo lo que necesite la tarea, por ejemplo worlds:write para editar borradores o worlds:publish para publicar. GET /me necesita account:read.

Un permiso nunca concede más de lo que puede hacer la persona que creó el token, y ese rol se vuelve a leer en cada solicitud. Los ids de otro espacio responden 404, así que un token no puede descubrir lo que no debe ver.

Los permisos sensibles son opcionales

Los permisos que llegan a direcciones de suscriptores, mensajes de visitantes, facturación, eliminación, escrituras DNS, gastos, cambios de equipo o webhooks nunca vienen marcados. Añadir uno te pide iniciar sesión de nuevo. Sus herramientas MCP permanecen ocultas hasta que el token los tiene.

Algunas acciones nunca están disponibles para un token: decidir una aprobación, eliminar o restaurar casas y cuentas (necesitan un inicio de sesión reciente en la propia aplicación y responden 403 reauthentication_required) y exportar datos.

Caducidad, rotación y revocación

• Los tokens caducan a los 30 días de forma predeterminada y a los 90 días como máximo.
• Solo se guarda un hash, así que un token perdido no se puede volver a mostrar. Crea una conexión nueva.
• Para rotar, crea una conexión nueva, cambia tu cliente a ella y revoca la antigua. La revocación se aplica en la siguiente solicitud, incluido el trabajo que un agente tuviera en cola.

Errores esperables

• 401: el token falta, es desconocido, caducó, fue revocado o es de la otra audiencia.
• 403 insufficient_scope: al token le falta un permiso. context.required_scope lo indica y la respuesta lleva una cabecera WWW-Authenticate.
• 404: el recurso no existe en el espacio de trabajo de este token.

OAuth todavía no está disponible

Los clientes de agentes que solo admiten inicio de sesión con OAuth todavía no pueden conectarse. Por eso /.well-known/oauth-protected-resource/mcp no anuncia ningún servidor de autorización. Usa un token de conexión en la configuración de cabeceras del cliente.