WorkOS lança registro de agentes para autenticação automatizada

O que é o registro de agentes

O Agent Registration permite que agentes de IA e clientes baseados em modelos de linguagem obtenham credenciais de identidade de serviços que usam AuthKit. O fluxo foi desenhado para clientes programáticos, com instruções legíveis por máquina, pouca interação e gerenciamento seguro de credenciais, em vez de depender de fluxos OAuth voltados a usuários em navegadores. O recurso precisa ser habilitado no ambiente; a documentação orienta contatar a equipe de contas da WorkOS caso ele ainda não esteja disponível.

Os agentes descobrem os endpoints por meio de metadados padronizados. A API protegida aponta para um documento de metadados de recurso, que identifica o servidor de autorização; seus metadados, por sua vez, incluem o bloco agent_auth com os endpoints de registro. A WorkOS também gera um arquivo auth.md, com instruções e comandos adaptados à configuração do ambiente. O arquivo pode ser hospedado na raiz do domínio da aplicação, preferencialmente por meio de um proxy reverso para a versão hospedada pela WorkOS, embora a URL hospedada possa ser acessada diretamente para testes.

Tipos de identidade e vinculação ao usuário

Há três tipos de registro. anonymous cria uma identidade sem vínculo com usuário e entrega uma asserção imediatamente; a vinculação posterior é opcional. service_auth é usado quando o agente conhece o e-mail do usuário e exige uma cerimônia de confirmação. refresh serve para renovar uma asserção próxima do vencimento, usando um token de atualização anterior.

A documentação recomenda service_auth quando os dados pertencem a usuários. Para recursos de uma organização, registros anônimos podem permitir exploração imediata, desde que recebam apenas permissões não confiáveis e limitadas. Operações sensíveis devem depender de permissões confiáveis, disponíveis depois da vinculação.

Na cerimônia padrão, o agente inicia uma tentativa, apresenta ao usuário uma URL de verificação e recebe um código curto lido pelo usuário após o login no AuthKit. O agente envia esse código com o token da tentativa e, se a confirmação for concluída, recebe uma asserção de identidade e um token de atualização. Também é possível realizar a cerimônia em uma interface própria: o servidor vincula a tentativa à identidade do usuário por uma API administrativa e exibe o código na aplicação. Nesse caso, a aplicação precisa autenticar previamente o usuário, pois a WorkOS verifica a correspondência de e-mail, mas não confirma quem está vendo a interface.

Quando o usuário pertence a várias organizações, o servidor deve informar qual organização será usada. Sem essa seleção, a API retorna um erro específico e a lista de organizações disponíveis.

Credenciais, permissões e operação

Depois de obter a asserção, o agente a troca por um token de acesso ou uma chave de API. O ambiente define o tipo e a duração da credencial. Tokens de acesso de curta duração podem ser validados localmente mediante verificação de assinatura e expiração; chaves de API precisam de validação no servidor. A aplicação também pode consultar o registro completo do agente, incluindo identidade, organização, status e datas.

O sistema separa permissões não confiáveis, concedidas antes da confirmação, de permissões confiáveis, liberadas após a cerimônia. O painel da WorkOS permite ativar ou desativar métodos de registro, escolher credenciais e prazos, configurar permissões por nível de confiança e acompanhar registros com status como não verificado, verificado, expirado ou revogado. Assim, o recurso fornece um fluxo padronizado para identificar agentes, vinculá-los a usuários ou organizações e controlar o acesso deles a APIs.