AgentAuth

Auth0, mas para agentes. Serviço de identidade e autenticação para agentes de IA.

Documentação

AgentAuth

Serviço de identidade e autenticação para agentes de IA. Emite credenciais verificáveis, gerencia ciclos de vida de chaves de API e fornece fluxos semelhantes a OAuth para interações máquina a máquina.

Servidor MCP

AgentAuth está disponível como um servidor MCP (Model Context Protocol) — nenhum código de cliente HTTP é necessário. Qualquer agente compatível com MCP pode autenticar e gerenciar permissões por meio de chamadas de ferramenta padrão.

O endpoint MCP está integrado à API do AgentAuth em /mcp. Nenhuma instalação separada é necessária.

Configuração

Hospedado (recomendado)

Adicione isso à configuração do seu cliente MCP e pronto:

{
  "mcpServers": {
    "agentauth": {
      "url": "https://agentauth.radi.pro/mcp"
    }
  }
}

Locais de configuração específicos do cliente

Cliente	Arquivo de configuração
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Claude Code (projeto)	`.claude/settings.json`
Claude Code (global)	`~/.claude/settings.json`
Cursor (global)	`~/.cursor/mcp.json`
Cursor (projeto)	`.cursor/mcp.json`
VS Code / Copilot	`settings.json` do usuário ou do espaço de trabalho em `github.copilot.chat.mcpServers`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
Continue.dev	`~/.continue/config.json`
Zed	`~/.config/zed/settings.json` em `context_servers`

Todos usam a mesma URL: https://agentauth.radi.pro/mcp

Modo local / stdio

Para ambientes de desenvolvimento ou sem conexão externa:

cd mcp-server
uv pip install -e .

{
  "mcpServers": {
    "agentauth": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/agent-auth/mcp-server", "agentauth-mcp"],
      "env": {
        "AGENTAUTH_URL": "https://agentauth.radi.pro"
      }
    }
  }
}

Auto-hospedagem

Se você executar sua própria instância do AgentAuth, o endpoint MCP estará automaticamente disponível em /mcp. Defina AGENTAUTH_URL para sua instância:

AGENTAUTH_URL=https://your-agentauth-instance.com

Variáveis de Ambiente

Variável	Obrigatória	Descrição
`AGENTAUTH_URL`	Sim (modo stdio)	URL base do serviço AgentAuth
`AGENTAUTH_API_KEY`	Não	Chave de API padrão usada por `authenticate` quando nenhuma é fornecida

Ao usar o endpoint /mcp hospedado diretamente, nenhuma variável de ambiente é necessária no cliente.

Fluxo de Uso Típico

1. quickstart          → register agent + get API key + access token (first run only)
2. authenticate        → exchange saved API key for a fresh access token
3. [do work]           → pass access_token to list_agents, create_delegation, check_permission, etc.
4. refresh_token       → get a new token pair before the access token expires
5. revoke_token        → invalidate tokens when done (optional)

Ferramentas Disponíveis

`discover`

Obtenha as capacidades e endpoints do servidor AgentAuth.

Retorna tipos de concessão suportados, escopos disponíveis, tempos de vida de token e todas as URLs de endpoint. Chame isso primeiro para entender o que o serviço oferece.

discover()

`quickstart`

Registre um novo agente raiz e obtenha credenciais em uma única chamada. A maneira mais rápida de começar.

Retorna identidade do agente, chave de API (mostrada uma vez — salve imediatamente), token de acesso, token de atualização e carimbos de data/hora de expiração.

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome legível do agente, ex.: `"my-data-pipeline"`
`agent_type`	string	Sim	Um de: `orchestrator`, `autonomous`, `assistant`, `tool`
`description`	string	Não	Propósito do agente

quickstart(
  name="my-pipeline",
  agent_type="autonomous",
  description="Processes nightly ETL jobs"
)

A resposta inclui:

agent — identidade registrada (id, name, agent_type, trust_level, …)
api_key — chave de API bruta, salve agora
access_token — token Bearer pronto para uso (válido por 15 min)
refresh_token — use antes que o token de acesso expire
expires_at / refresh_before — carimbos de data/hora ISO-8601

`authenticate`

Troque uma chave de API por um token de acesso (concessão client_credentials).

Parâmetro	Tipo	Obrigatório	Descrição
`api_key`	string	Não	Chave de API do AgentAuth. Recorre à variável de ambiente `AGENTAUTH_API_KEY`
`scopes`	string[]	Não	Escopos a solicitar. Padrão: todos os escopos que a credencial permite

authenticate(
  api_key="ak_live_...",
  scopes=["api.read", "agents.write"]
)

Retorna: access_token, refresh_token, token_type, expires_in, expires_at, refresh_before

`refresh_token`

Troque um token de atualização por um novo par de token de acesso + atualização.

Use quando o token de acesso estiver próximo da expiração — verifique refresh_before na resposta de authenticate.

Parâmetro	Tipo	Obrigatório	Descrição
`refresh_token_value`	string	Sim	Token de atualização de uma chamada anterior de `authenticate` ou `quickstart`

refresh_token(refresh_token_value="rt_...")

`introspect_token`

Verifique se um token é válido e inspecione suas declarações (RFC 7662).

Retorna active: true/false mais as declarações decodificadas (scopes, agent_type, trust_level, expiration) se ativo.

Parâmetro	Tipo	Obrigatório	Descrição
`token`	string	Sim	O token de acesso ou atualização a inspecionar

introspect_token(token="eyJ...")

`revoke_token`

Revogue um token de acesso ou atualização imediatamente (RFC 7009).

O token é adicionado à lista de bloqueio e invalidado. Idempotente — revogar um token já revogado é bem-sucedido.

Parâmetro	Tipo	Obrigatório	Descrição
`token`	string	Sim	Token a revogar

revoke_token(token="eyJ...")

`create_credential`

Emita uma nova chave de API para um agente.

O raw_key é retornado uma vez — salve-o imediatamente. Leituras subsequentes mostram apenas o prefixo da chave.

Parâmetro	Tipo	Obrigatório	Descrição
`agent_id`	string	Sim	UUID do agente
`access_token`	string	Sim	Token Bearer
`scopes`	string[]	Não	Restrições opcionais de escopo para a nova chave

create_credential(
  agent_id="01927...",
  access_token="eyJ...",
  scopes=["api.read"]
)

`rotate_credential`

Revogue uma chave de API existente e emita uma substituição em uma única operação atômica.

Retorna novos campos de credencial, o novo raw_key (salve-o) e o antigo credential_id.

Parâmetro	Tipo	Obrigatório	Descrição
`credential_id`	string	Sim	UUID da credencial a rotacionar
`access_token`	string	Sim	Token Bearer

rotate_credential(
  credential_id="01928...",
  access_token="eyJ..."
)

`revoke_credential`

Revogue permanentemente uma chave de API. Irreversível.

Parâmetro	Tipo	Obrigatório	Descrição
`credential_id`	string	Sim	UUID da credencial a revogar
`access_token`	string	Sim	Token Bearer

revoke_credential(
  credential_id="01928...",
  access_token="eyJ..."
)

`create_delegation`

Delegue um subconjunto de suas permissões a outro agente.

O delegado só pode receber escopos que o delegador já possui. As delegações podem ser encadeadas até max_chain_depth vezes.

Parâmetro	Tipo	Obrigatório	Descrição
`delegate_agent_id`	string	Sim	UUID do agente que recebe as permissões
`scopes`	string[]	Sim	Escopos a delegar (devem ser um subconjunto dos seus)
`access_token`	string	Sim	Token Bearer do agente delegador
`max_chain_depth`	int	Não	Quantas vezes o delegado pode re-delegar (padrão: 3)
`expires_in_hours`	int	Não	Expiração da delegação em horas a partir de agora

create_delegation(
  delegate_agent_id="01929...",
  scopes=["api.read", "agents.read"],
  access_token="eyJ...",
  max_chain_depth=1,
  expires_in_hours=24
)

`check_permission`

Avaliação de política em modo de simulação — verifica se um agente tem permissão para executar uma ação sem realmente aplicá-la. Útil para verificações pré-voo.

Parâmetro	Tipo	Obrigatório	Descrição
`agent_id`	string	Sim	UUID do agente a verificar
`action`	string	Sim	Um de: `read`, `write`, `delete`, `execute`, `delegate`, `admin`
`resource`	string	Sim	Caminho do recurso, ex.: `"/api/v1/credentials"`
`access_token`	string	Sim	Token Bearer

check_permission(
  agent_id="01927...",
  action="write",
  resource="/api/v1/credentials",
  access_token="eyJ..."
)

Retorna: allowed: true/false, detalhes da política correspondente, raciocínio da decisão.

`list_agents`

Liste agentes registrados com paginação.

Parâmetro	Tipo	Obrigatório	Descrição
`access_token`	string	Sim	Token Bearer
`limit`	int	Não	Máximo de resultados, 1–100 (padrão: 50)
`offset`	int	Não	Deslocamento de paginação (padrão: 0)

list_agents(access_token="eyJ...", limit=10, offset=0)

`get_agent`

Obtenha detalhes completos de um agente específico.

Retorna campos do agente (id, name, agent_type, trust_level, status) mesclados com metadados (is_root, is_active).

Parâmetro	Tipo	Obrigatório	Descrição
`agent_id`	string	Sim	UUID do agente
`access_token`	string	Sim	Token Bearer

get_agent(agent_id="01927...", access_token="eyJ...")

Tipos de Agente

Tipo	Descrição
`orchestrator`	Coordena outros agentes; alta confiança
`autonomous`	Agentes autônomos executando tarefas longas
`assistant`	Agentes interativos respondendo a solicitações de usuários
`tool`	Agentes utilitários de propósito específico

Tempos de Vida de Token

Token	Tempo de vida padrão
Token de acesso	15 minutos
Token de atualização	7 dias
Chaves de API	Configurável (sem expiração padrão)

Exemplo de SDK Python

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client("https://agentauth.radi.pro/mcp") as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()

        # Register and get credentials
        result = await session.call_tool("quickstart", {
            "name": "my-agent",
            "agent_type": "autonomous",
        })
        api_key = result.content[0].text  # save this

        # Authenticate on subsequent runs
        auth = await session.call_tool("authenticate", {"api_key": api_key})
        token = auth.content[0].text  # access_token

API REST

O servidor MCP encapsula a API REST do AgentAuth. A documentação interativa da API está disponível em:

https://agentauth.radi.pro/docs