Esta página te lleva de cero a la primera llamada exitosa. Son cinco pasos y valen igual para credenciales y documentos; donde cambia algo, está separado en pestañas.
Después de esto, el paso siguiente es crear el esquema, según lo que vayas a emitir: Esquema SD-JWT, Esquema mDoc o Esquema de documento.
Entornos
| Test | Producción | |
|---|---|---|
| API | https://test-api-sovra.flagonsa.com |
https://api.sovra.io |
| Dashboard | https://test-issuer-sovra.flagonsa.com |
https://issuer.sovra.io |
En los ejemplos, $BASE_URL es la URL de la API del entorno que uses:
export BASE_URL="https://test-api-sovra.flagonsa.com"
export SOVRA_API_KEY="sovra_sk_..."RPC y Chain ID de SovraChain, y la especificación OpenAPI
| Test | Producción | |
|---|---|---|
| RPC de SovraChain | https://rpc.testnet.sovra.io |
https://rpc.sovra.io |
| Chain ID | 65536101 |
65536001 |
La especificación OpenAPI del entorno está siempre disponible en GET $BASE_URL/openapi/api: es la fuente de verdad si algo en esta documentación queda desactualizado. La versión navegable está en la Referencia de API.
Configuración
Acceder al dashboard
El acceso es por invitación: el equipo de Sovra te manda un correo con el enlace de alta. Al aceptarlo se crean tu usuario, una organización y un primer workspace.
El workspace es tu espacio de trabajo: tiene su propia identidad (DID), sus esquemas, sus API keys y sus webhooks, aislados de los demás. Podés crear más desde Settings → Workspaces (por ejemplo, uno por dependencia).
Esperar el DID del workspace
Al crearse, el workspace registra su identidad en SovraChain. El resultado es un DID, el identificador público de tu organización:
did:sovra:0xcda79e1ee5612c230a6faf68236e3679b0579baeTarda algunos minutos. Cuando el DID aparece en Settings → Workspace, está listo. Mientras tanto, la API responde
workspace_not_provisioned.Más sobre el aprovisionamiento
Mientras el aprovisionamiento no termine, crear un esquema o una oferta, emitir un documento o listar documentos responde:
{ "error": "workspace_not_provisioned" }Si ya tenías un webhook configurado, al terminar recibís el evento
identity.did-generated(ver Webhooks).mDoc necesita además la dirección EOA. De la dirección EOA del workspace se deriva el docType generado (
io.sovra.<dirección>.<schema_id>.1), y es la clave de indexación de los mapas de revocación. Mientras el aprovisionamiento no concluya, el docType se muestra vacío en el dashboard.Crear una API key
Settings → API keys → New API key (necesitás rol de administrador). La clave
sovra_sk_...se muestra una sola vez: guardala en tu gestor de secretos. Si la perdés, revocás esa y creás otra.Todas las llamadas la usan así:
Authorization: Bearer sovra_sk_...La key está atada al workspace, así que nunca mandás un
workspace_id. Podés tener varias activas (una por sistema) y revocar cualquiera sin tocar las demás.Configurar el webhook
Casi todo lo que hace Sovra termina después de la llamada, y el resultado te llega por webhook: un aviso que Sovra le manda a tu servidor. Sin webhook, tenés que consultar el
GETcorrespondiente cada tanto.En Settings → Webhooks:
- Cargá la URL de tu servidor (
https://tu-servidor.com/webhooks/sovra). - Elegí los eventos. No hay comodín: un evento que no suscribís no llega nunca.
- Guardá el secreto
whsec_…. Se muestra una sola vez y sirve para comprobar que cada aviso viene de Sovra.
Suscribí
credential.issued,presentation.verifiedypresentation.failed. Si vas a revocar por API, agregácredential.revoked,credential.suspended,credential.unsuspendedycredential.status-change-failed.Los mismos que SD-JWT VC:
credential.issued,presentation.verifiedypresentation.failed, y los de cambio de estado si revocás por API.credential.issuedllega conformat: "mso_mdoc"y eldoc_type.Suscribí
document.status-changed: avisa cuando el documento quedóanchoredy ya se puede entregar. Si no podés recibir webhooks, consultáGET /api/v1/issuer/documentshasta veranchored.Hasta 10 endpoints por workspace. Los payloads, la firma HMAC y los reintentos están en Webhooks.
- Cargá la URL de tu servidor (
Hacer la primera llamada
Con el DID listo y la API key en mano, listá lo emitido. Al principio, la lista viene vacía:
curl -s "$BASE_URL/api/v1/issuer/credentials" \ -H "Authorization: Bearer $SOVRA_API_KEY"{ "credentials": [] }La misma llamada que SD-JWT VC sirve para probar la conexión:
curl -s "$BASE_URL/api/v1/issuer/credentials" \ -H "Authorization: Bearer $SOVRA_API_KEY"Probar de una vez el esquema mDoc
Con un esquema
mso_mdocya creado yregistered(ver Esquema mDoc), crear una oferta confirma de una vez el esquema, la API key y el aprovisionamiento:curl -s -X POST "$BASE_URL/api/v1/issuer/credential-offer" \ -H "Authorization: Bearer $SOVRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "schema_id": "licencia_de_conducir", "claims": { "family_name": "Lovelace", "given_name": "Ada", "birth_date": "1815-12-10", "issue_date": "2026-01-15", "expiry_date": "2036-01-15", "issuing_country": "MX", "issuing_authority": "Nuevo León", "document_number": "NL-0001", "un_distinguishing_sign": "MEX", "portrait": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==", "driving_privileges": [{ "vehicle_category_code": "B" }], "age_over_18": true } }'Una respuesta
201conoffer_uriconfirma que todo está en orden.curl -s "$BASE_URL/api/v1/issuer/documents" \ -H "Authorization: Bearer $SOVRA_API_KEY"{ "documents": [] }Si algo falla:
{ "error": "invalid_api_key" }: la clave está mal copiada, revocada, o falta el prefijoBearer(con B mayúscula).{ "error": "workspace_not_provisioned" }: el workspace todavía no tiene DID. Esperá unos minutos.
Checklist
- El workspace muestra su DID
did:sovra:0x…(y, para mDoc, su dirección EOA) en Settings → Workspace. - Tenés una API key
sovra_sk_…guardada fuera del código fuente. - Tu webhook responde
2xxpor HTTPS, valida la firma y tiene suscritos los eventos que necesitás. Guardaste el secretowhsec_…. -
GET /api/v1/issuer/credentials(oGET /api/v1/issuer/documents) responde200.
Lo siguiente es crear un esquema del tipo correcto y esperar a que quede registered. Ver Esquemas.
Recursos
- Colecciones de Postman (importalas y configurá la URL base y la API key): Credenciales, mDoc, mDoc con namespace propio y Documentos firmados.
- Especificación OpenAPI en vivo:
GET $BASE_URL/openapi/api.
Convenciones de la API
Reglas que valen para toda la API servidor-a-servidor (/api/v1). Los endpoints, uno por uno, están en la Referencia de API.
Formato: JSON, cabeceras, fechas e identificadores
| Cuerpo | JSON (Content-Type: application/json), salvo la lista de estado, que responde application/jwt. Techo de 8 MB; por encima, 413. |
Cabecera Accept |
Toda ruta JSON exige un Accept que admita application/json (*/*, el default de curl, lo admite). Cualquier otra cosa es un 406 antes de llegar al endpoint. Eso incluye GET /api/v1/status/… con Accept: application/jwt, aunque esa ruta responda con un JWT. |
| Nomenclatura | snake_case en toda la API. |
| Fechas | ISO 8601 en UTC (2026-08-26T04:41:32Z). Dentro de un SD-JWT, iat y exp son segundos Unix. |
| Identificadores | UUID, salvo schema_id, que es el slug del esquema. |
x-request-id |
Toda respuesta la trae. Citala cuando reportes un problema. |
No hay endpoints específicos de mDoc. La creación del esquema, la emisión y la verificación usan los mismos endpoints que una credencial SD-JWT; el formato lo determina el format del esquema. Lo que reside únicamente en el dashboard es el registro del document signer, la admisión de una raíz IACA, las API keys, los webhooks y el layout de los documentos. La API del dashboard (/dashboard/*) y la de la wallet (/wallet/*) quedan fuera de estas convenciones.
Autenticación y zonas de la API (incluye CORS)
Todos los endpoints, salvo los públicos, requieren la API key de workspace (Authorization: Bearer sovra_sk_...).
- El esquema
Beareres sensible a mayúsculas:beareren minúsculas devuelve401 invalid_api_key. - El workspace se deduce de la clave: no se envía
workspace_iden ningún request. - Un recurso de otro workspace responde
404, como si no existiera, nunca403. Vale para credenciales, documentos, esquemas y verificaciones. - El request se rechaza si su workspace, o la organización de ese workspace, están desactivados. Desactivar un tenant no revoca sus claves: este control es lo que las detiene.
| Código | error |
Cuándo |
|---|---|---|
401 |
invalid_api_key |
Sin cabecera Authorization, malformada, o clave desconocida o revocada. |
403 |
workspace_inactive |
El workspace de la clave está desactivado. |
403 |
organization_inactive |
La organización del workspace está desactivada. |
La API tiene dos zonas, y la diferencia está en el path:
| Zona | Path | Autenticación |
|---|---|---|
| Emisor (y verificador) | /api/v1/issuer/…, /api/v1/verifier/… |
Authorization: Bearer sovra_sk_... |
| Pública | /api/v1/documents/…, /api/v1/status/… |
Ninguna. Para documentos públicos, tener el id es toda la autorización. |
- Una API key no sustituye una sesión. Un documento privado leído por la zona pública devuelve
401 authentication_requiredincluso si mandás la key en el header. Los documentos privados solo se abren con sesión del dashboard. - CORS. La zona pública responde
Access-Control-Allow-Origin: *. La zona emisor no, así que el navegador la bloquea: hace falta un proxy del lado servidor (que es, además, donde tiene que vivir la API key).
Errores: los dos formatos de respuesta
Los errores del endpoint comparten un sobre:
{ "error": "schema_not_found", "details": "…" }error es un código estable, pensado para que lo lea tu código. details es opcional, y según el error es un string, una lista de strings o un objeto campo → mensajes. Las fallas de validación usan validation_error con mensajes por campo:
{ "error": "validation_error", "details": { "validity_period": ["has invalid format"] } }Los errores del framework usan otro sobre, porque se producen antes de que el endpoint corra:
{ "errors": { "detail": "Bad Request" } }| Código | Causa |
|---|---|
400 |
Cuerpo JSON malformado, o un id malformado. |
404 |
Ninguna ruta coincide. |
406 |
Accept no admite el formato de la ruta. |
413 |
Cuerpo de más de 8 MB. |
500 |
Error no manejado (Internal Server Error). |
Cada código de error, con su causa y su solución, está en Errores.
Paginación y rate limit
Solo pagina GET /api/v1/verifier/verifications, con limit (1–200, default 50) y offset (≥ 0, default 0). Los demás listados devuelven todo, sin paginación ni filtros. En particular, GET /api/v1/issuer/documents ignora los query params y crece con el workspace.
Solo POST /api/v1/issuer/credential-offer tiene rate limit: 120 solicitudes por minuto por IP de origen, contadas por separado en cada nodo de la API. Por encima responde 429 con {"error": "too_many_requests"}. No se envía Retry-After ni cabeceras X-RateLimit-*: esperá y reintentá.
Operaciones asincrónicas
Cuatro escrituras devuelven antes de que su desenlace sea definitivo. La respuesta confirma que la solicitud se aceptó; el webhook, o el GET correspondiente, dice cómo terminó.
| Operación | Respuesta inmediata | El estado final llega como |
|---|---|---|
| Emitir un documento | 201, status: "signed" |
document.status-changed → anchored o failed |
| Cambiar el estado de una credencial | 202, el destino en pending_status |
credential.revoked / .suspended / .unsuspended, o credential.status-change-failed |
| Crear una oferta de credencial | 201 con la oferta |
credential.issued cuando el holder la canjea |
| Crear una verificación | 201 con la URI de la solicitud |
presentation.verified o presentation.failed |
Los estados de cada elemento están en Ciclo de vida.
Límites y cuotas
| Recurso | Límite |
|---|---|
POST /api/v1/issuer/credential-offer |
120 req/min por IP de origen, contadas por nodo |
| Cuerpo de un request | 8 MB |
| Vigencia de una oferta | 24 horas |
| Vigencia de una sesión de verificación | 10 minutos |
limit en el listado de verificaciones |
200 (y es el único listado que pagina) |
Adjunto de un claim attachment |
560.000 bytes, y uno solo por esquema |
Imágenes del diseño (thumbnail.uri, hero.uri) |
256 KB |
| Intentos de un cambio de estado on-chain | 5 |
| Intentos de anclaje de un documento | 5 |
| Throughput del anclaje | Del orden de 5 documentos por bloque y por nodo |
| Layout de un documento | 3 MB |
Techo de un QR con el credential de un documento (nivel L) |
~2953 bytes |
| Timeout de entrega de webhook | 5 segundos |
| Reintentos de webhook | 8 intentos, con backoff: ~1,5 horas en total |
| Endpoints de webhook por workspace | 10 |
| Desfasaje horario tolerado en el KB-JWT | ±5 minutos |