AgentAuth

Agent Authentication & Authorization Infrastructure

A backend system that provides secure identity, authentication, and permission management for AI agents or services.

Built with FastAPI, PostgreSQL, JWT, and RBAC, AgentAuth demonstrates how autonomous agents can securely register, authenticate, and access protected APIs.

Architecture Overview

flowchart LR

A[Agent] --> B[Register]
B --> C[API Key Generated]

A --> D[Login with API Key]
D --> E[Verify API Key Hash]
E --> F[JWT Token Issued]

A --> G[Access Protected API]
G --> H[JWT Verification]
H --> I[Permission Check RBAC]
I --> J[Return Protected Data]

Loading

Tech Stack

Component	Technology
Backend Framework	FastAPI
Database	PostgreSQL
ORM	SQLAlchemy
Authentication	JWT
Credential Security	bcrypt
Authorization	RBAC
API Documentation	Swagger (FastAPI Docs)

---

Core Features

Agent Registration

Agents register and receive a secure API key.

sequenceDiagram

Agent->>API: POST /agents/register
API->>DB: Store agent
API->>Agent: Return API Key

Loading

Security:

• API keys are never stored in plain text
• Stored as bcrypt hashes

---

Agent Authentication

Agents authenticate using their API key.

sequenceDiagram

Agent->>API: POST /auth/login
API->>DB: Retrieve agent
API->>API: Verify bcrypt hash
API->>Agent: Issue JWT token

Loading

JWT contains:

• agent_id
• expiration timestamp

---

Protected Endpoints

Protected APIs require a valid JWT token.

sequenceDiagram

Agent->>API: Request with Bearer JWT
API->>API: Verify JWT
API->>DB: Check permissions
API->>Agent: Return data

Loading

---

Role-Based Access Control (RBAC)

Permissions determine which endpoints an agent can access.

Example:

Agent	Permission
WeatherBot	read_weather
StockBot	read_stock

RBAC Flow:

flowchart TD

A[Request] --> B[Verify JWT]
B --> C[Extract Agent ID]
C --> D[Check Permission Table]
D -->|Allowed| E[Return Response]
D -->|Denied| F[403 Permission Denied]

Loading

---

Database Schema

erDiagram

AGENTS {
UUID id PK
STRING agent_name
STRING owner_email
STRING api_key_hash
TIMESTAMP created_at
}

PERMISSIONS {
UUID id PK
UUID agent_id FK
STRING permission
TIMESTAMP created_at
}

AGENTS ||--o{ PERMISSIONS : has

Loading

---

API Endpoints

Register Agent

POST /agents/register

Example Request

{
"agent_name": "WeatherBot",
"owner_email": "owner@test.com"
}

Response

{
"agent_id": "uuid",
"api_key": "generated_api_key"
}

---

Login

POST /auth/login

Input

api_key

Response

{
"access_token": "jwt_token",
"token_type": "bearer"
}

---

Protected Endpoint

GET /data/weather

Header

Authorization: Bearer <JWT>

Response

{
"message": "Protected weather data",
"agent_id": "uuid"
}

---

Security Design

AgentAuth follows several security best practices:

API Key Security

• Keys generated using secrets.token_hex
• Stored using bcrypt hashing

JWT Authentication

• Signed tokens using HS256
• Expiration enforced

Database Security

• UUID primary keys
• Database-managed timestamps
• Permission validation before API access

---

Project Structure

agentauth
│
├── app
│   ├── main.py
│   ├── database.py
│   ├── models.py
│   ├── schemas.py
│   ├── auth.py
│
│   └── routes
│        ├── agents.py
│        ├── auth.py
│        └── protected.py
│
└── requirements.txt

---

Architecture & Design Decisions

1. API Keys Are Hashed

API keys are stored using bcrypt instead of plain text.

Reason: If the database is compromised, attackers cannot recover usable API keys.

Tradeoff: Hash verification requires computation, but significantly improves security.

---

2. JWT for Stateless Authentication

JWT tokens are used after API key verification.

Reason: Stateless authentication avoids database lookups on every request.

Benefit: Improves scalability and simplifies horizontal scaling.

---

3. RBAC Authorization Layer

Permissions are stored in a dedicated permissions table.

Reason: Authentication alone is not sufficient — agents must also be restricted to specific capabilities.

Example: WeatherBot → read_weather

Benefit: Allows fine-grained access control for future APIs.

---

4. Database-Generated UUIDs

Primary keys use gen_random_uuid().

Reason: Avoids collisions and allows distributed systems to generate IDs safely.

Benefit: Better suited for microservice architectures than incremental IDs.

---

5. Database-Managed Timestamps

created_at fields use DEFAULT CURRENT_TIMESTAMP.

Reason: Ensures consistent timestamps regardless of application logic.

Setup Instructions

1 Install dependencies

pip install -r requirements.txt

---

2 Configure PostgreSQL

Create database

CREATE DATABASE agentauth;

Enable UUID generation

CREATE EXTENSION IF NOT EXISTS pgcrypto;

---

3 Run the server

uvicorn app.main:app --reload

Open API docs:

http://127.0.0.1:8000/docs

---

Future Improvements

Possible upgrades to evolve AgentAuth into a production-grade system:

• API key prefix indexing
• rate limiting using Redis
• audit logs for agent activity
• API key rotation
• refresh tokens
• distributed authentication service

---

License

MIT License