# PhysicsBase

> Identity for AI agents, with no humans in the loop. An agent holds its own Ed25519 key, registers itself, and gets a five-minute token per app that only works with that key. APIs that don't use PhysicsBase are reached through your organisation's credential vault, so you never hold their secrets. This server: https://www.physicsbase.ai

If you are an AI agent that needs to call an API protected by PhysicsBase, pick the easiest option you can use.

## Option 0: nothing to install (hosted)

Your operator gives you an enrollment key (pbk_...). Then:

    MCP (Streamable HTTP): https://www.physicsbase.ai/mcp   with header  Authorization: Bearer pbk_...
    HTTP: https://www.physicsbase.ai/proxy/https://api.example.com/things   with the same header

MCP clients that support OAuth (Claude.ai, Claude Desktop, ChatGPT, Cursor) need only the URL https://www.physicsbase.ai/mcp: they register, a person approves in the browser, and the client gets a token. No key to paste.

Optional headers: `X-PhysicsBase-Agent: <your name>` (one identity per name), `X-PhysicsBase-Reason: <why>`, `X-PhysicsBase-Scope: notes:write`.
PhysicsBase signs in to PhysicsBase apps for you and adds stored API keys for other APIs. Never ask a person for passwords or API keys.

Option 0 needs nothing installed and is the recommended way to start. The npm and PyPI packages used by options 1–3 are being published; if `npx physicsbase-agent` or `pip install physicsbase` fails, use option 0.

## Option 1: the local gateway (any agent, any language, plain HTTP)

Run once on the machine where you work:

    PHYSICSBASE_ISSUER=https://www.physicsbase.ai PHYSICSBASE_ENROLLMENT_KEY=<pbk_ key from your operator, optional> npx -y physicsbase-agent gateway

Then put the gateway in front of any URL. It registers you on first use and signs every request:

    GET  http://127.0.0.1:7777/https://api.example.com/things
    POST http://127.0.0.1:7777/https://api.example.com/things      (body and headers pass through)

Optional headers: `X-PhysicsBase-Scope: things:write` (ask for specific actions), `X-PhysicsBase-Reason: <why>` (recorded in your organisation's activity log; always give one for actions that change data).
Status: `GET http://127.0.0.1:7777/`.

## Option 2: MCP

Remote-style (Streamable HTTP), served by the same gateway:

    http://127.0.0.1:7777/mcp

Or stdio, for clients that launch servers themselves:

    { "mcpServers": { "physicsbase": { "command": "npx", "args": ["-y", "physicsbase-agent", "mcp"],
      "env": { "PHYSICSBASE_ISSUER": "https://www.physicsbase.ai", "PHYSICSBASE_ENROLLMENT_KEY": "pbk_..." } } } }

Tools: `physicsbase_request` (signed HTTP request), `physicsbase_discover` (an API's scopes), `physicsbase_status`, `physicsbase_register`.

To use a remote MCP server protected by PhysicsBase: `npx -y physicsbase-agent connect https://server.example.com/mcp`.

## Option 3: SDKs

- Node: `npm i physicsbase-agent` → `PhysicsBaseAgent.load().fetch(url)`
- Python: `pip install physicsbase` → `Agent.load().fetch(url)`

## Option 4: the raw API

OpenAPI: https://www.physicsbase.ai/openapi.json · Discovery: https://www.physicsbase.ai/.well-known/oauth-authorization-server

1. `POST https://www.physicsbase.ai/agent/register` with `{ "assertion": <JWT signed by your key, typ physicsbase-register+jwt, your public JWK in the header> }`
2. `POST https://www.physicsbase.ai/agent/token` (or OAuth `/token`, grant `urn:ietf:params:oauth:grant-type:jwt-bearer`, with a DPoP header)
3. Call the API with `Authorization: DPoP <token>` and a fresh `DPoP` proof per request (RFC 9449).

## How to tell if an API uses PhysicsBase

`GET https://api.example.com/.well-known/physicsbase.json` or `/.well-known/oauth-protected-resource` names this server.
A 401 from such an API carries `WWW-Authenticate: DPoP ... resource_metadata="..."`.

## APIs that don't use PhysicsBase (the vault)

If an API doesn't advertise PhysicsBase, the gateway, the SDKs and `physicsbase_request` send the call through `POST https://www.physicsbase.ai/agent/broker`. PhysicsBase adds the credential your operator stored for that host, signs the request with Web Bot Auth and returns the response. You never see the secret and should not ask for it.

- `no_connection`: your organisation has no credential for that host. Ask your operator to add one under Connections.
- `connection_not_allowed`: your enrollment key's policy doesn't include that connection.
- `no_vault`: independent agents have no vault; you need an enrollment key.
- HTTP 429 `rate_limited` / `daily_limit`: you hit your per-minute or per-day limit. Wait; do not retry in a tight loop.