api reference

auth.notme.bot

signet identity authority API. bridge certificates via OIDC token exchange, GHA automation, and agent registration.

base https://auth.notme.bot

certificate exchange

POST /cert
Generalized cert exchange. Present any proof, get a scoped bridge cert. This is the core signet protocol endpoint.
request
{ "proof": { "type": "session" }, "scopes": ["bridgeCert"] } // Today only the `session` proof type is wired. `oidc` and `bootstrap` return 501; the OIDC path will return only when the issuer is in `OIDC_ALLOWED_ISSUERS` (server env), the audience matches `OIDC_AUDIENCE`, and the alg is RS256 or ES256 — see @notme/contract for the baseline.
response
{ "certificate": "-----BEGIN CERTIFICATE-----\n...", "private_key": "-----BEGIN PRIVATE KEY-----\n...", "expires_at": 1711670400, "subject": "a1b2c3d4-...", "authority": { "epoch": 1, "key_id": "3b8b237e" }, "principal_id": "a1b2c3d4-...", "scopes": ["bridgeCert"], "auth_method": "passkey" }
Proof types: session (passkey cookie), oidc (any JWT), bootstrap (deployer code). Scopes are intersected with the principal's capability grants.
POST /cert/gha
Exchange a GitHub Actions OIDC token for a 5-minute bridge certificate. No stored secrets needed — the OIDC JWT is the credential. Edge-handled (no VPC roundtrip).
authorization

Bearer <GHA OIDC token> with audience notme.bot

request
curl -X POST https://auth.notme.bot/cert/gha \ -H "Authorization: Bearer ${TOKEN}"
response
{ "certificate": "-----BEGIN CERTIFICATE-----\n...", "private_key": "-----BEGIN PRIVATE KEY-----\n...", "expires_at": 1711670400, "subject": "repo:agentic-research/signet:ref:refs/heads/main", "claims": { "repository": "agentic-research/signet", "ref": "refs/heads/main", "sha": "abc123...", "actor": "github-actions", "workflow": "ci.yml", "run_id": "12345", "event_name": "push" } }
Allowed owners: agentic-research (configurable via GHA_ALLOWED_OWNERS). Ephemeral P-256 keypair generated at edge — private key returned once, never stored.
POST /exchange-token
Exchange an OIDC token for a bridge certificate. Used by signet auth login (human auth flow). Proxied to signet authority on Fly.
authorization

OIDC token from OAuth callback flow.

POST /api/cert/register
Register an agent identity using a GitHub PAT. For headless/automated environments where browser OAuth isn't possible. Proxied to signet authority on Fly.

discovery

GET /.well-known/signet-authority.json
Authority discovery document. Lists all endpoints, supported algorithms, and grant types. Analogous to OpenID Connect's /.well-known/openid-configuration, but signet consumes OIDC — it does not issue tokens.
response
{ "issuer": "https://auth.notme.bot", "exchange_token_endpoint": "https://auth.notme.bot/exchange-token", "cert_gha_endpoint": "https://auth.notme.bot/cert/gha", "registration_endpoint": "https://auth.notme.bot/api/cert/register", "ca_bundle_endpoint": "https://auth.notme.bot/.well-known/ca-bundle.pem", "algorithms_supported": ["Ed25519"], "grant_types_supported": [ "oidc_token_exchange", "github_actions_oidc", "github_pat" ], "cert_types_supported": ["bridge_certificate"], "documentation": "https://notme.bot/architecture" }
GET /.well-known/ca-bundle.pem
CA trust anchor — the authority's Ed25519 public key in PEM format. Configure MCP servers and verifiers with this to validate bridge certificates. Served from the SigningAuthority Durable Object (edge-fast, zero VPC roundtrip).
response
-----BEGIN PUBLIC KEY----- MCowBQYDK2VwAyEA... -----END PUBLIC KEY-----
Cache-Control: 1 hour. Key is generated in CF and never leaves — there is no PEM file to exfiltrate.
GET /
Content-negotiated landing. Returns HTML (browser) or JSON authority metadata (Accept: application/json).

health

GET /healthz
Health check. Proxied to signet authority on Fly.

authentication model

signet is not an identity provider — it is an identity attester. You own your key. signet signs a short-lived certificate binding your public key to your verified identity.

Three grant types:

oidc_token_exchangeHuman OAuth → browser flow via signet auth login
github_actions_oidcGHA CI → POST /cert/gha with OIDC JWT (zero secrets)
github_patHeadless agent → POST /api/cert/register with PAT

All certificates are Ed25519-signed X.509 with custom OID extensions for subject identity and issuance time, matching the Go authority format.