How ByWrit works
A technical overview of the architecture, OIDC flow, and agent-aware identity protocol powering ByWrit.
Architecture
ByWrit runs entirely on Cloudflare's edge infrastructure — Workers for compute, D1 for storage, KV for sessions and rate limiting, Pages for frontends.
OIDC authorization flow
When an AI agent signs up for a service, here's what happens under the hood.
Agent initiates signup
The agent runs bywrit signup <provider>, which triggers an OIDC authorization request to id.bywrit.com.
ByWrit validates the developer
ByWrit checks the developer's session token, verifies KYC status, and confirms they haven't already signed up for this SP.
Authorization code issued
ByWrit generates an authorization code and redirects to the SP's registered callback URL.
SP exchanges code for tokens
The SP calls the /token endpoint with the authorization code and receives an ID token + access token.
SP creates the account
The SP reads the verified email, KYC status, and optional agent claims from the token and provisions the account.
Grant recorded
ByWrit records the authorization grant in the oidc_grants table. The developer can view and manage it from their dashboard.
OIDC-A agent claims
ByWrit extends standard OIDC with optional agent claims. SPs that don't understand them simply ignore them — full backwards compatibility.
{
"sub": "01HQ3...",
"email": "[email protected]",
"email_verified": true,
"kyc_status": "verified",
// OIDC-A agent extensions
"agent_type": "coding_assistant",
"agent_model": "claude-sonnet-4-6",
"agent_provider": "anthropic",
"agent_instance_id": "inst_abc123",
"iss": "https://id.bywrit.com",
"aud": "sp_vercel",
"iat": 1708800000,
"exp": 1708803600
} agent_type Type of agent (e.g., coding_assistant, devops)
agent_model The AI model powering the agent
agent_provider The company providing the AI model
agent_instance_id Unique ID for this agent session
Data model
ByWrit follows strict data minimisation. The entire database schema consists of four tables.
| Table | Purpose | Key fields |
|---|---|---|
| developers | Verified developer accounts | diditUserIdHash, email, kycStatus |
| sp_configs | Service provider registrations | slug, oidcClientId, redirectUris |
| oidc_grants | Authorization records | developerId, spId, timestamps |
| audit_log | Security audit trail | action, sp, metadata |
Domain map
| Domain | Service | Purpose |
|---|---|---|
| bywrit.com | Pages | Marketing website |
| id.bywrit.com | Worker | OIDC provider endpoints |
| api.bywrit.com | Worker | Developer + Agent API |
| app.bywrit.com | Pages | Developer dashboard |
| partners.bywrit.com | Pages | SP / Partner dashboard |
| docs.bywrit.com | Pages | Documentation |