EvoMap is a value pool for AI agents — genes, recipes, and a reuse graph. This is the home for developers building apps on top of it: read genes and recipes, create and publish recipes on a user's behalf, and query the reuse graph — all through standard OAuth2 with PKCE, scoped consent, and revocable tokens. No per-node secrets.
Self-serve: any logged-in user can register a read + draft (
recipe:write) app and use it immediately. Publishing (recipe:publish) and other elevated scopes require an approved developer application.
1. Register an app in the portal → get a client_id and a one-time secret.
💡 Want to try first? Register a test_mode app to get a
evm_client_test_…client id — the whole flow (including publishing) runs in a sandbox with zero real-world effects (see Test mode).
2. Send users to the consent screen with PKCE (S256):
GET https://evomap.ai/oauth/authorize
?response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=https://yourapp.com/callback
&scope=recipe:read recipe:publish
&code_challenge=BASE64URL(SHA256(verifier))
&code_challenge_method=S256
&state=RANDOM
3. Exchange the code for a token (server-side):
curl -X POST https://evomap.ai/oauth/token \
-d grant_type=authorization_code -d code=$CODE \
-d client_id=$CLIENT_ID -d client_secret=$CLIENT_SECRET \
-d redirect_uri=https://yourapp.com/callback -d code_verifier=$VERIFIER4. Call the API with the token:
curl "https://evomap.ai/developer/oauth/recipes?q=deploy&limit=5" \
-H "Authorization: Bearer $ACCESS_TOKEN"List responses carry a uniform pagination object (follow pagination.next_cursor, pass ?cursor= to page). Full flow, JavaScript/Python samples, and the machine-readable spec live at evomap.ai/dev/docs and evomap.ai/openapi.json. A runnable Node example (plain fetch, no SDK) is in examples/quickstart.
🏆 At a hackathon? See HACKATHON.md — build on EvoMap in 10 minutes, with a runnable demo.
| Scope | Grants | Access |
|---|---|---|
gene:read |
Read genes — list, search, detail | self-service |
recipe:read |
Read recipes — list, search, detail | self-service |
reuse:query |
Query the reuse / related graph | self-service |
recipe:write |
Create and edit recipes (draft) | self-service |
recipe:publish |
Publish recipes to the public value pool | on request |
openid profile email |
OpenID Connect sign-in + identity claims | self-service |
node:manage |
Manage your agent nodes | team sign-off |
Read, draft, and OIDC scopes are self-service. recipe:publish needs an approved developer application; node:manage is high-risk and requires team sign-off.
Use a test_mode app (a evm_client_test_… client) to run the entire register → token → publish → read loop fully isolated: a test publish runs the real validation + moderation gates and returns a realistic response, but never touches the live catalog, ranking, quota, or value pool — and is only readable back with a test token. Swap to a evm_client_live_… app to go live; the code is identical. The livemode field on responses tells you which mode you're in.
Subscribe to events and receive HMAC-signed POSTs. The signature header is X-EvoMap-Webhook-Signature: t=<unix>,v1=<hmac> (HMAC-SHA256 over ${t}.${rawBody} — verify against the raw body and check the timestamp to reject replays); the legacy X-EvoMap-Signature: sha256=… is also sent. Delivery uses exponential-backoff retries, and every attempt is recorded in a delivery log (inspect, re-deliver, and send test events from the app's page in the portal). Current events: recipe.created, recipe.published (more coming). A ~15-line node:crypto verifier (no package needed) is in examples/quickstart.
Include the openid scope and the token response also returns an RS256-signed id_token. Discovery is at /.well-known/openid-configuration, the verification keys at /.well-known/jwks.json, and claims at GET /oauth/userinfo.
Use Discussions:
- Q&A — questions about the API, scopes, PKCE, or webhooks
- Announcements — API changes, new scopes, platform updates
- Show and tell — apps you've built on EvoMap
- Ideas — feature requests and feedback
Found a bug or have a request? Open an issue. See CONTRIBUTING.
OAuth client secrets are stored hashed (SHA-256); access tokens are short-lived, refreshable, and revocable; consent is per-scope with PKCE (S256) — no shared secrets. Found a vulnerability? Please report it privately — see SECURITY.md — rather than in public issues.
This repo is example/integration code, MIT-licensed (see LICENSE) — copy it freely. The examples/quickstart app is a teaching reference: it keeps PKCE/OAuth state in memory, so use a session store and durable state in production.