mirror of
https://github.com/agentrhq/authsome.git
synced 2026-09-19 01:34:19 +08:00
Manoj Bajaj
29 lines
1.9 KiB
Plaintext
29 lines
1.9 KiB
Plaintext
---
|
||
title: "Architecture"
|
||
description: "How Authsome separates identity, storage, and authentication."
|
||
---
|
||
|
||
Authsome separates credential management into distinct, highly-focused layers. The goal is to provide a unified auth broker for AI agents that cleanly isolates who is acting, how credentials are encrypted, and how OAuth or API flows are executed.
|
||
|
||
Authsome is primarily consumed as a **sidecar proxy** (via `authsome run`), intercepting the agent's outgoing requests and injecting credentials. Alternatively, it can be embedded as a Python library.
|
||
|
||
## The core concepts
|
||
|
||
Authsome’s architecture relies on four foundational concepts:
|
||
|
||
1. **Identity**: The cryptographic agent making the request (using Ed25519 keys and `did:key` DIDs). It proves its identity to the daemon using Proof-of-Possession (PoP) JWTs.
|
||
2. **Principal**: The logical owner (e.g., a human user or team). An identity must claim a principal to access any credentials.
|
||
3. **Vault**: The encrypted storage for credentials, owned by exactly one principal.
|
||
4. **Auth flows**: The stateless execution of OAuth 2.0 (PKCE, Device Code, DCR) or API key collection.
|
||
|
||
## Motivation
|
||
|
||
AI agents need external APIs to do their jobs. Historically, giving them access meant one of two bad options:
|
||
|
||
- Exposing raw API keys in environment variables, which leaks credentials to sub-processes.
|
||
- Building complex OAuth flows directly into the agent's code.
|
||
|
||
Authsome fixes this by acting as a local credential broker. It handles the whole authentication lifecycle—from browser logins to token refresh—and securely injects those tokens into the agent’s requests via a local proxy.
|
||
|
||
By separating the Vault (storage), Identity (the acting agent), and Auth logic (how to get tokens), Authsome ensures agents only get the credentials they have permission to use, exactly when they need them, without ever touching the raw secret.
|