AgentAuth

Identity and authentication service for AI agents. Issues verifiable credentials, manages API key lifecycles, and provides OAuth-like flows for machine-to-machine interactions.

MCP Server

AgentAuth is available as an MCP (Model Context Protocol) server — no HTTP client code required. Any MCP-compatible agent can authenticate and manage permissions through standard tool calls.

The MCP endpoint is built into the AgentAuth API at /mcp. No separate install needed.

Setup

Hosted (recommended)

Add this to your MCP client config and you're done:

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

Client-specific config locations

All use the same URL: https://agentauth.radi.pro/mcp

Local / stdio mode

For development or air-gapped environments:

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"
      }
    }
  }
}

Self-hosting

If you run your own AgentAuth instance, the MCP endpoint is automatically available at /mcp. Set AGENTAUTH_URL to your instance:

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

Environment Variables

When using the hosted /mcp endpoint directly, no environment variables are needed on the client.

Typical Usage Flow

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)

Available Tools

discover

Get AgentAuth server capabilities and endpoints.

Returns supported grant types, available scopes, token lifetimes, and all endpoint URLs. Call this first to understand what the service offers.

discover()

quickstart

Register a new root agent and get credentials in one call. The fastest way to get started.

Returns agent identity, API key (shown once — save immediately), access token, refresh token, and expiry timestamps.

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

Response includes:

• agent — registered identity (id, name, agent_type, trust_level, …)
• api_key — raw API key, save it now
• access_token — ready-to-use Bearer token (valid 15 min)
• refresh_token — use before access token expires
• expires_at / refresh_before — ISO-8601 timestamps

authenticate

Exchange an API key for an access token (client_credentials grant).

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

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

refresh_token

Exchange a refresh token for a new access + refresh token pair.

Use when the access token is near expiry — check refresh_before from the authenticate response.

refresh_token(refresh_token_value="rt_...")

introspect_token

Check whether a token is valid and inspect its claims (RFC 7662).

Returns active: true/false plus decoded claims (scopes, agent_type, trust_level, expiration) if active.

introspect_token(token="eyJ...")

revoke_token

Revoke an access or refresh token immediately (RFC 7009).

The token is added to the blocklist and invalidated. Idempotent — revoking an already-revoked token succeeds.

revoke_token(token="eyJ...")

create_credential

Issue a new API key for an agent.

The raw_key is returned once — save it immediately. Subsequent reads only show the key prefix.

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

rotate_credential

Revoke an existing API key and issue a replacement in one atomic operation.

Returns new credential fields, the new raw_key (save it), and the old credential_id.

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

revoke_credential

Permanently revoke an API key. Irreversible.

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

create_delegation

Delegate a subset of your permissions to another agent.

The delegate can only receive scopes the delegator already holds. Delegations can be chained up to max_chain_depth times.

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

check_permission

Dry-run policy evaluation — checks whether an agent is allowed to perform an action without actually enforcing it. Useful for pre-flight checks.

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

Returns: allowed: true/false, matched policy details, decision reasoning.

list_agents

List registered agents with pagination.

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

get_agent

Get full details for a specific agent.

Returns agent fields (id, name, agent_type, trust_level, status) merged with metadata (is_root, is_active).

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

Agent Types

Token Lifetimes

Python SDK Example

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

REST API

The MCP server wraps the AgentAuth REST API. Interactive API docs are available at:

https://agentauth.radi.pro/docs