agentauthlayer

Unified SDK and local control plane package for Agent Auth.

Token-first developer flow

You can now create project-scoped tokens from:

• the Project Settings page in the UI
• the Tokens page in the UI
• the CLI with agentauth token create

These tokens support one visible token model with richer internal semantics:

• purpose=sync for registration and sync flows
• purpose=runtime for runtime execution flows
• purpose=automation for service or CI style automation
• optional agent_id binding for runtime-oriented tokens

Runtime binding

Runtime authorization now enforces stronger execution binding checks for project-scoped flows:

• project scope mismatches are denied before policy evaluation
• agent/principal mismatches are denied before policy evaluation
• execution context automatically carries project, agent, principal, and token-purpose context into authorization checks
• runtime-bound tokens now carry first-class project_id, agent_id, and purpose fields, with scope-based fallback for older tokens

Use the resulting token in code directly:

from agent_auth.client import AuthAPIClient

client = AuthAPIClient(
    base_url="http://127.0.0.1:8002",
    token="YOUR_PROJECT_TOKEN",
)

Or store it locally for CLI + SDK reuse:

agentauth login --base-url http://127.0.0.1:8002 --token YOUR_PROJECT_TOKEN --email admin@agentauth.dev

Create a bound runtime token from the CLI

agentauth token create \
  --project ai-platform \
  --name research-runtime-token \
  --purpose runtime \
  --agent-id research-agent-01 \
  --scope docs.read

Then use it directly in code:

from agent_auth import AuthAPIClient

client = AuthAPIClient(token="YOUR_RUNTIME_TOKEN")
ctx = client.execution_context()

print(ctx.project_id)
print(ctx.agent_id)
print(ctx.context.get("token_purpose"))

agentauthlayer helps you:

• start a local Agent Auth backend and UI with one command
• authenticate once and reuse local credentials
• register agents from code
• sync tool and capability definitions
• evaluate permissions against the control plane
• apply permission checks inside runtime functions

This package now ships as a unified developer install containing:

• the reusable Python SDK layer
• the local control plane backend runtime
• the packaged admin UI assets

Install

pip install agentauthlayer

Enterprise Features

• PostgreSQL Support: Natively run on postgres or sqlite via STORAGE_BACKEND env variables.
• Project-Scoped Capabilities: Tool and permission catalogs are fully isolated per project.
• Enforced Project Roles: True RBAC enforcing admin, member, and viewer roles per-project.
• Developer CLI Lifecycle: Use agentauth dev, agentauth server status, and agentauth server stop for seamless local testing.

Quickstart

1. Start the local control plane

For a local developer setup, start Agent Auth with one command:

agentauth up

This starts the packaged local control plane on http://127.0.0.1:8002 by default.

If you want a different port:

agentauth up --port 8014

2. First-time developer setup

For a fresh deployment:

1. Open the UI in your browser.
2. Create the first super admin password.
3. Create your first project.
4. Then log in from the CLI.

Open the UI with:

agentauth ui --base-url http://127.0.0.1:8002

Then log in once:

agentauth login --base-url http://127.0.0.1:8002

This stores local credentials so your code can connect without manually pasting a token every time.

Useful follow-up commands:

agentauth whoami
agentauth logout
agentauth ui
agentauth dev
agentauth server status
agentauth server stop

If the deployment has not been initialized yet, agentauth login will tell you to finish setup in the UI first.

3. Define tools and agents in code

from agent_auth import register_tool, register_agent, require_permission

@register_tool(action="math.compute", description="Run approved math jobs")
@require_permission("math.compute", resource="math/basic")
def add(a: int, b: int, agent_id: str | None = None, role: str | None = None, context: dict | None = None):
    return a + b

register_agent(
    agent_id="math-agent",
    name="Math Agent",
    owner="you@company.com",
    role="research_agent",
    project_id="ai-platform",
    scopes=[],
)

4. Sync everything with one command

agentauth sync --module your_module_name

This imports the module, discovers registered tools and agents, syncs capability definitions, and creates agents through the control plane.

SDK client usage

from agent_auth import AuthAPIClient

client = AuthAPIClient()

agent = client.create_agent(
    agent_id="research-bot-01",
    name="Research Bot 01",
    owner="vaibhav@company.com",
    role="research_agent",
    scopes=[],
    project_id="ai-platform",
)

print(agent)

Environment variables

If you prefer non-interactive configuration, the SDK also supports environment variables:

export AGENT_AUTH_URL=http://127.0.0.1:8002
export AGENT_AUTH_TOKEN=YOUR_ADMIN_OR_SERVICE_TOKEN

AGENT_AUTH_TOKEN is typically a bearer token, often represented as a long JWT string.

Recommended usage:

• use agentauth login for local human developer workflows
• use AGENT_AUTH_TOKEN for CI, automation, or service-driven execution

If an env token expires, requests will fail until you replace it or log in again. Avoid committing tokens into source control or long-lived shared .env files.

Resolution order used by AuthAPIClient():

1. explicit constructor arguments
2. environment variables
3. stored local credentials from agentauth login

Common tasks

Sync tools manually

client.sync_tools([
    {"action": "tool.search_web", "description": "Search the web"},
    {"action": "docs.read", "description": "Read protected docs"},
])

Evaluate access

decision = client.evaluate(
    principal_id="research-bot-01",
    action="tool.search_web",
    resource="web/*",
    role="research_agent",
)

print(decision)

Fetch or delete an agent

agent = client.get_agent("research-bot-01")
print(agent)

result = client.delete_agent("research-bot-01")
print(result)

CLI equivalent:

agentauth delete-agent research-bot-01

Public package scope

This package provides:

• the Python SDK (agent_auth)
• local control plane startup via agentauth up
• packaged backend runtime (auth_app)
• packaged admin UI assets
• CLI helpers for login, sync, and agent cleanup
• registry-based tool and agent sync
• permission evaluation helpers

Suitable use cases

• Python agent runtimes
• tool-based workflows
• service-to-control-plane integrations
• local development with stored credentials
• CI or automation using environment variables

Requirements

• Python 3.10+
• access to a running Agent Auth control plane

Notes

The package naming model is:

• install name: agentauthlayer
• CLI: agentauth
• Python import namespace: agent_auth

The import path remains:

from agent_auth import ...

while the published package name is:

pip install agentauthlayer