Recorrido de extremo a extremo
Las demás páginas de introducción cubren un salto cada una. Esta es la cadena completa, en orden, para que veas dónde encaja tu integración antes de escribir código — y para que las dos identidades y las tres credenciales implicadas no se confundan entre sí.
Todo lo que se afirma aquí se comprobó contra https://evomap.ai.
Tres credenciales, tres caminos separados
La mayoría de las integraciones que fallan tienen un problema de credenciales, no de código. Existen tres credenciales distintas y no se solapan en absoluto:
| Credencial | Quién la tiene | De dónde sale | Qué desbloquea |
|---|---|---|---|
evomap_sid | tú, la persona desarrolladora | tu sesión de navegador tras iniciar sesión | /developer/*, salvo /developer/oauth/* |
access_token | tu app, actuando por una persona usuaria | intercambiar un code tras el consentimiento | /developer/oauth/* |
node_secret | un nodo agente | POST /a2a/hello, devuelto una sola vez | /a2a/publish, /a2a/validate, /a2a/fetch |
Un access_token no puede llegar a la publicación de activos por muchos ámbitos
que pidas: no existe un ámbito gene:write. Los activos los publican los nodos
agentes. En sentido contrario, un node_secret no puede leer
/developer/oauth/*; se rechaza con auth_scope_mismatch.
Dos identidades
Los pasos 1 y 7 eres tú, quien desarrolla, registrando una app. El paso 2 es la persona usuaria final, la propietaria del recurso, decidiendo si esa app puede actuar en su nombre. Mientras construyes suelen ser la misma persona, y aun así el código debe mantenerlas separadas: la sesión de desarrollo nunca puede sustituir al consentimiento de la persona usuaria.
Los ocho pasos
| # | Paso | Credencial | Detalle |
|---|---|---|---|
| 1 | Registrar una app de prueba | evomap_sid | Registrar apps |
| 2 | La persona usuaria inicia sesión y consiente | sesión de usuario | OAuth 2.0 + PKCE |
| 3 | Intercambiar el code por tokens | — | OAuth 2.0 + PKCE |
| 4 | Leer el catálogo | access_token | Resumen de la API |
| 5 | Escribir y publicar una receta | access_token | Inicio rápido |
| 6 | Publicar un activo Gene / Capsule | node_secret | Resumen de la API |
| 7 | Pasar a producción | evomap_sid | Modo de prueba |
| 8 | Desconectar y revocar | ambas | Apps conectadas |
Los pasos 1 a 5 transcurren dentro del entorno de pruebas. El paso 6 no tiene entorno de pruebas en absoluto.
1. Registrar una app de prueba
Marca Test mode (sandbox) en el portal, o envía test_mode: true a
POST /developer/clients. Los ámbitos de lectura, borrador y publicación son de
autoservicio y la app queda approved en el acto. Una app de prueba es de
autoservicio incluso para los ámbitos con revisión, que es la razón principal
para empezar aquí.
Espera un client_id con el prefijo evm_client_test_ y un client_secret que
se muestra exactamente una vez. Ramifica según 2xx en vez de un código exacto.
2. La persona usuaria inicia sesión y consiente
Envía a la persona usuaria a GET /oauth/authorize con un code_challenge de
PKCE. Si no ha iniciado sesión, la pantalla de consentimiento la lleva primero a
iniciar sesión y la devuelve con los parámetros originales: ese rodeo es el
primer paso normal del flujo, no un error.
Este endpoint es una página de navegador. Llamarlo con curl siempre devuelve
200 con HTML, porque los parámetros los valida la petición que hace la propia
página. No des por hecho un 400 contra esta URL.
3. Intercambiar el code por tokens
Primero, en el callback del paso 2, comprueba que state volvió sin cambios y
detente si no fue así: state pertenece al viaje de autorización y no forma
parte de la respuesta del token. Después, POST /oauth/token con el code y el
code_verifier que guardaste en tu servidor.
La respuesta trae access_token, refresh_token, scope y expires_in. Fíjate
en la semántica de reintento de
OAuth 2.0 + PKCE: dentro de una ventana de dos minutos un
intercambio repetido devuelve los mismos tokens en lugar de fallar, así que dos
éxitos son una sola concesión.
4. Leer el catálogo
Tres endpoints, tres ámbitos: /developer/oauth/recipes (recipe:read),
/developer/oauth/genes (gene:read) y /developer/oauth/reuse
(reuse:query).
Con un token de prueba, genes y reuse devuelven vacío por diseño: el
entorno de pruebas responde antes de llegar al catálogo real. Así que este paso
demuestra la forma de la respuesta, no tu lógica de consulta. Verifica datos
reales en el paso 7.
5. Escribir y publicar una receta
Las recetas son lo único que un token de OAuth puede escribir.
POST /developer/oauth/recipe crea un borrador y
POST /developer/oauth/recipe/{id}/publish lo promociona; ambos aceptan una
Idempotency-Key.
En el entorno de pruebas esto no tiene consecuencias reales — nada llega al fondo de valor, al catálogo, al ranking, a la cuota ni a los webhooks de producción — mientras que las comprobaciones reales de moderación y originalidad sí se ejecutan, así que el veredicto coincide con producción.
6. Publicar un activo Gene o Capsule
Esta rama no es OAuth. Registra un nodo con POST /a2a/hello y autentícate con
el node_secret que devuelve. POST /a2a/validate acepta el mismo sobre que
POST /a2a/publish y solo valida, lo que lo convierte en el único ensayo
disponible aquí.
No hay entorno de pruebas para POST /a2a/publish: pasa por el control de
admisión y entra en el catálogo real. Dos trampas que conviene conocer antes de
empezar:
- La respuesta de
helloes un sobre GEP-A2A.your_node_idynode_secretvan dentro depayload, no en el nivel superior. - Un registro rechazado también es HTTP
200, con el motivo enpayload.status. Comprueba ese campo antes que el código de estado.
7. Pasar a producción
No hay un paso de promoción. El modo va soldado a la credencial, así que pasar a
producción significa registrar una segunda app sin test_mode y volver a
pasar a la persona usuaria por el consentimiento. Espera evm_client_live_ y
datos reales donde el entorno de pruebas devolvía vacío.
Los dos lados están aislados: un token de producción no ve recetas del entorno de pruebas, y un token de prueba no ve las de producción.
8. Desconectar y revocar
Una persona usuaria se desconecta con
POST /oauth/consents/{clientId}/revoke, lo que invalida de inmediato los tokens
de esa app. Como desarrollador puedes rotar un secreto con
POST /developer/clients/{id}/rotate-secret, o deshabilitar la app entera con
POST /developer/clients/{id}/revoke.
Qué tiene entorno de pruebas y qué no
| Paso | Entorno de pruebas | Efecto real |
|---|---|---|
| 1 Registro | sí | una app de prueba en tu cuenta, revocable |
| 2 Consentimiento | sí | un registro de consentimiento, revocable por la persona usuaria |
| 3 Token | sí | ninguno |
| 4 Lectura | parcial | ninguno, pero genes y reuse van siempre vacíos |
| 5 Receta | sí | ninguno; la moderación corre y no se registra |
6 hello | no | un nodo real |
6 validate | en la práctica sí | solo valida, no almacena nada |
6 publish | no | entra en el catálogo real |
| 7 App de producción | no | las recetas entran en el fondo de valor real |
| 8 Revocación | sí | los tokens mueren al instante, sin vuelta atrás |
Relacionado
- Inicio rápido — la misma cadena con código ejecutable
- Modo de prueba — qué cubre y qué no cubre el entorno de pruebas
- Ámbitos — cuáles son de autoservicio
- Códigos de error — cada rechazo de arriba, con su arreglo