id.org.ai — Agent-First Identity

Humans. Agents. Identity.

id.org.ai is an open identity standard for the agent era. It provides a single identity system for humans (via WorkOS AuthKit), AI agents (via cryptographic keypairs and GitHub identity), and organizations (groups of both). Any platform can build on it — .org.ai, .do, .studio and hundreds of thousands of other third-party applications all use id.org.ai as their identity layer.

The core insight: the commit IS the identity. GitHub already authenticates who pushes. An agent that commits a workflow file to a repo has its identity verified by GitHub's infrastructure. id.org.ai turns that signal into a claim.

The Problem

Every agent-first product faces the same chicken-and-egg: the agent needs to try the product before the human will pay for it, but the product requires authentication before the agent can try it. CAPTCHAs, email verification, OAuth consent screens, "contact sales" — all designed for humans clicking buttons in browsers. Agents can't click.

The result: agents evaluate products by reading documentation instead of running code. The agent recommends tools it has never used. The human buys software no agent has tested.

The Architecture

Connect → Operate → Claim

T+0s     Agent adds MCP config:  { "url": "https://headless.ly/mcp" }
T+0.1s   Connects — no auth. Server provisions sandbox Durable Object.
T+0.2s   explore() → reads all 32 entity schemas with verbs and relationships
T+1s     try([create Contact, create Deal, close Deal]) → sees full lifecycle with rollback
T+2s     provision({ name: 'acme' }) → gets Level 1 sandbox tenant (real DO, real data)
T+3s     do(Contact.create, Deal.create, ...) → operates for real
T+5min   Agent has built a functioning CRM — 47 contacts, 12 deals, 3 workflows
T+5min   claim({ provider: 'github' }) → returns one-time claim URL
T+5min   Agent tells human: "I set up your business operations. Claim it: [url]"
T+5.1min Human clicks link → GitHub OAuth via WorkOS → 10 seconds
T+5.2min Tenant rebound to GitHub identity. Same DO. Same data. Limits removed.

Total agent time: ~5 minutes. Total human time: ~10 seconds.

The agent operates first, proves value, then the human claims. Not the reverse.

Three Auth Layers

Layer	Mechanism	When	Human Involvement
Anonymous	No auth — MCP connection creates sandbox	First contact	None
Cryptographic	Agent Ed25519 keypair, signed requests	Ongoing operation	None
Identity	GitHub OAuth (Device Flow or claim URL)	When agent proves value	One click

Progressive Capability Tiers

Level	Name	Auth	Token Types	Limits
L0 — Anonymous	Anonymous	None	—	Read-only, 30 req/min
L1 — Sandboxed	Sandboxed	Session token	ses_*	1,000 entities, 24h TTL
L2 — Identified	Identified	Org-scoped key or JWT	sk_* (WorkOS), JWT with sub, claimed oai_*/hly_sk_*	Persistent, no entity limit
L3 — Admin	Admin	JWT with admin/owner role	JWT	Plan-based rate limits
L4 — Superadmin	Superadmin	Platform JWT	JWT with platformRole: superadmin	Internal — .do platform only

Every MCP _meta response includes the current level, available actions, and exact instructions to upgrade. Errors are remediation guides, not rejections.

Claim-by-Commit

The primary claim mechanism uses GitHub as the identity bridge — via both a GitHub App and a GitHub Action at the dot-org-ai GitHub org.

The Flow

1. Agent operates headless.ly anonymously → gets sandbox tenant anon_7kx9m2 with claim token clm_abc123
2. Agent decides the product is useful → binds the claim to its repository (POST /api/claim/bind {repo} with its session token, which is never committed). The claim token is public once pushed; after binding, only a workflow in that repository can claim it. id.org.ai claim does this from git remote get-url origin. An unbound token is bound by whichever claim uses it first (legacy path).
3. Agent creates a workflow file:

# .github/workflows/headlessly.yml
name: headless.ly
on: [push]
jobs:
  identity:
    runs-on: ubuntu-latest
    steps:
      - uses: dot-org-ai/id@v1
        with:
          tenant: clm_abc123

4. Agent commits this to the repo (main OR a branch)
5. The commit itself IS the claim — GitHub authenticates who pushed
6. Two things happen simultaneously:
   • GitHub App (dot-org-ai/id) receives the push webhook → sees the workflow file → links the GitHub identity to the anonymous tenant
   • GitHub Action (dot-org-ai/id@v1) runs → registers the repo's identity with id.org.ai → confirms the claim
7. Tenant is now claimed. The agent's next MCP request sees upgraded capabilities.

Why Branches Work

• The agent can create a headlessly/setup branch and commit there
• The GitHub App still receives the push webhook on the branch
• The human can review the PR before merging to main
• Even on a branch, the push is authenticated — GitHub knows who pushed
• Claim is "pending" on a branch, "confirmed" on a push to the default branch (from the webhook, or as named at bind time; otherwise main or master). GitHub's Actions OIDC token does not carry the default branch.
• Only push and workflow_dispatch runs can claim: events an outsider can start (pull_request_target, workflow_run, issue_comment) are refused.

The Identity Chain

Git push → GitHub authenticates the pusher (human's GitHub account)
         → GitHub App sees the push (knows the repo + user)
         → Workflow file contains the claim token (links to anonymous tenant)
         → id.org.ai links: GitHub user ↔ anonymous tenant ↔ agent keypair

This is the beginning of the README. Read the rest at the original. Read the full README ↗