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"] } // or with OIDC: { "proof": { "type": "oidc", "token": "<JWT from any issuer>" } } // or bootstrap (deployer only): { "proof": { "type": "bootstrap", "code": "abc12345" } }
response
{ "certificates": { "mtls": "-----BEGIN CERTIFICATE-----\n...", "signing": "-----BEGIN CERTIFICATE-----\n..." }, "identity": "wimse://notme.bot/passkey/a1b2c3d4-...", "scopes": ["bridgeCert"], "expires_at": 1711670400, "subject": "a1b2c3d4-...", "binding": "9f86d081..." }
notme never sends a private key. The caller generates both keypairs locally with extractable: false and proves possession; only certificates come back. Earlier revisions of this page showed a private_key field — no endpoint has ever returned one.
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 "Content-Type: application/json" \ -d '{"oidc_token":"<GHA OIDC JWT>", "public_keys":{"mtls":"<P-256 SPKI PEM>","signing":"<Ed25519 SPKI PEM>"}, "proofs":{"mtls":"<base64url>","signing":"<base64url>"}}'
response
{ "certificates": { "mtls": "-----BEGIN CERTIFICATE-----\n...", "signing": "-----BEGIN CERTIFICATE-----\n..." }, "identity": "wimse://notme.bot/gha/agentic-research/signet", "scopes": ["bridgeCert"], "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 — self-signed X.509 CA certificate (Ed25519). Upload to CF mTLS trust store or use with any X.509 verifier to validate bridge certificates. Served from the SigningAuthority Durable Object (edge-fast, zero VPC roundtrip).
response
-----BEGIN CERTIFICATE----- MIIBFjCByaADAgEC... -----END CERTIFICATE-----
Cache-Control: 1 hour. CA:TRUE, KeyUsage: keyCertSign|cRLSign. 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.