Acesso restrito que continua sendo seu

Conexões são tokens do espaço de trabalho

Proprietários e administradores criam conexões na página Desenvolvedores. Cada conexão é um token de portador vinculado a um espaço de trabalho e a um público: tokens rest (sw_rest_...) funcionam só em /api/v1 e tokens mcp (sw_mcp_...) só em /mcp.

Envie o token no cabeçalho Authorization. Nunca o coloque em uma URL, query string, arquivo de importação ou código que chegue ao navegador.

Authorization: Bearer sw_rest_...

Permissões restringem o que o seu papel permite

Uma conexão nova começa com as permissões de leitura: workspaces:read, catalog:read e worlds:read. Adicione só o que a tarefa precisa, por exemplo worlds:write para editar rascunhos ou worlds:publish para publicar. GET /me precisa de account:read.

Uma permissão nunca concede mais do que a pessoa que criou o token pode fazer, e esse papel é lido de novo a cada requisição. Ids de outro espaço respondem 404, então um token não descobre o que não deve ver.

Permissões sensíveis são opcionais

Permissões que alcançam endereços de inscritos, mensagens de visitantes, cobrança, exclusão, escrita de DNS, gastos, mudanças na equipe ou webhooks nunca vêm marcadas. Adicionar uma pede que você entre de novo. As ferramentas MCP correspondentes ficam ocultas até o token tê-las.

Algumas ações nunca ficam disponíveis para um token: decidir uma aprovação, excluir ou restaurar casas e contas (exigem um login recente no próprio aplicativo e respondem 403 reauthentication_required) e exportar dados.

Validade, rotação e revogação

• Tokens expiram em 30 dias por padrão e em no máximo 90 dias.
• Só um hash é guardado, então um token perdido não pode ser mostrado de novo. Crie uma nova conexão.
• Para rotacionar, crie uma nova conexão, troque o cliente para ela e revogue a antiga. A revogação vale na próxima requisição, inclusive para trabalho que um agente tenha deixado na fila.

Erros esperados

• 401: o token está ausente, é desconhecido, expirou, foi revogado ou é do outro público.
• 403 insufficient_scope: falta uma permissão ao token. context.required_scope indica qual, e a resposta traz um cabeçalho WWW-Authenticate.
• 404: o recurso não existe no espaço de trabalho deste token.

OAuth ainda não está disponível

Clientes de agentes que só aceitam login com OAuth ainda não conseguem se conectar. Por isso /.well-known/oauth-protected-resource/mcp não anuncia nenhum servidor de autorização. Use um token de conexão nas configurações de cabeçalho do cliente.