Una credencial emitida se puede suspender por un tiempo o revocar para siempre. El estado se publica en SovraChain, así que lo ve cualquier verificador, no solo los que usan Sovra. Todo lo de esta página vale igual para SD-JWT VC y para mDoc.
Los estados
stateDiagram-v2
[*] --> pending: crear la oferta
pending --> expired: 24 h sin canje
pending --> issued: el ciudadano escanea y acepta
issued --> suspended: suspender
suspended --> issued: reactivar
issued --> revoked: revocar
suspended --> revoked: revocar
expired --> [*]
revoked --> [*]
pending: la oferta existe, pero el ciudadano todavía no la escaneó.expired: la oferta pasó 24 horas sin que nadie la canjeara.issued: la credencial está en la wallet y es válida.suspended: sigue en la wallet, pero no pasa la verificación hasta que la reactives.revoked: anulada para siempre. No hay vuelta atrás.
El credential_id que te devolvió la oferta es el mismo durante todo el recorrido: con
él consultás y cambiás el estado. Para el panorama general, ver
Ciclo de vida.
Suspender, reactivar o revocar
Un solo endpoint, con el estado destino al final de la URL: suspended, issued
(para reactivar) o revoked.
curl -X PUT "$BASE_URL/api/v1/issuer/credentials/$CREDENTIAL_ID/status/revoked" \
-H "Authorization: Bearer $SOVRA_API_KEY"Para reactivar una credencial suspendida, el destino es issued (no active).
También podés hacerlo desde el dashboard, con rol de administrador del workspace. La
referencia de cada operación: Suspender,
Reactivar y Revocar.
Una credencial suspendida o revocada sigue en la wallet y se ve normal; lo que
cambia es que la verificación falla con credential_suspended o credential_revoked.
Si tu caso no tolera la ventana entre el 202 y la confirmación, tratala como revocada
en tu sistema desde el 202 y usá el webhook para confirmar.
Qué pasa entre el 202 y el webhook (pending_status)
La respuesta del PUT deja el estado actual en status y el destino en
pending_status:
{ "id": "b662aaad-d940-48fb-be9e-7194c76210ff", "status": "issued", "pending_status": "revoked" }sequenceDiagram
participant E as Tu sistema
participant S as Sovra
participant C as SovraChain
E->>S: PUT /credentials/{id}/status/revoked
S-->>E: 202 status=issued, pending_status=revoked
loop Hasta 5 intentos
S->>C: Escribe el bit en la lista de estado
end
alt La transacción confirma
S->>E: Webhook credential.revoked
else No confirma tras 5 intentos
S->>E: Webhook credential.status-change-failed
end- Si confirma:
statuspasa al destino,pending_statusse limpia y se disparacredential.revoked,credential.suspendedocredential.unsuspended. - Si no confirma tras 5 intentos:
statusqueda como estaba,pending_statusse limpia, el motivo queda enstatus_change_errory se disparacredential.status-change-failed. Recién entonces podés volver a pedir el cambio.
Los intentos intermedios no generan webhook. El payload de credential.revoked /
suspended / unsuspended no trae status (el nombre del evento es el estado nuevo);
el de credential.status-change-failed trae requested_status y el status sin
cambios. Los payloads están en Webhooks. También podés ver
pending_status y status_change_error con
GET /api/v1/issuer/credentials/{id}.
Un cambio pendiente a la vez. Pedir otro mientras el primero está en vuelo devuelve
409 status_change_pending.
No es idempotente. Revocar dos veces da 409 status_change_pending mientras la
primera se escribe, y 422 invalid_status_transition una vez que confirmó. Si
reintentás, tratá los dos como “ya está en camino o ya está” y consultá el estado antes
de considerarlo un fallo.
Los webhooks se disparan igual si el cambio se hizo desde el dashboard, así que sirven para sincronizar sistemas que no originaron la acción. No hay webhook cuando se crea la oferta, cuando vence sin canjearse ni cuando un canje falla.
El corte en la verificación es inmediato desde que el cambio llegó a la cadena: el estado se consulta on-chain en cada verificación, sin caché intermedia del lado del verificador de Sovra.
Transiciones permitidas y errores
| Desde | Hacia | ¿Permitido? | Webhook |
|---|---|---|---|
pending |
issued |
Sí, cuando el ciudadano canjea | credential.issued |
pending |
expired |
Sí, a las 24 h sin canje | Ninguno |
issued |
suspended |
Sí | credential.suspended |
suspended |
issued |
Sí (reactivar) | credential.unsuspended |
issued o suspended |
revoked |
Sí | credential.revoked |
revoked |
cualquiera | No: terminal | |
pending |
suspended / revoked |
No: todavía no hay credencial | |
| cualquiera | el mismo estado | No |
| HTTP | error |
Causa |
|---|---|---|
| 400 | unknown_status |
El destino no es revoked, suspended ni issued. |
| 401 | invalid_api_key |
Autorización ausente o inválida. |
| 404 | credential_not_found |
El UUID no existe en este workspace, o no es un UUID válido. Se controla antes que el destino. |
| 409 | workspace_not_provisioned |
El workspace todavía no tiene DID. |
| 409 | status_change_pending |
Otro cambio de esta credencial todavía no confirmó. Esperá el webhook. |
| 422 | credential_not_yet_issued |
El id es de una oferta pending: no hay credencial que revocar. |
| 422 | invalid_status_transition |
Cualquier cambio desde revoked (incluido reactivarla), o pasar al mismo estado. |
Más contexto en Errores de credenciales.
Cómo se publica el estado
Sovra usa el estándar W3C Bitstring Status List: cada workspace tiene en SovraChain una lista de bits de revocación y otra de suspensión, y cada credencial ocupa una posición. Revocar o suspender es prender su bit. Como la lista vive en la cadena, un verificador puede comprobar el estado sin llamar a Sovra (ver Verificar sin Sovra), y como descarga la lista entera, nadie puede saber a quién está verificando.
La Bitstring Status List en detalle
- Cada workspace mantiene dos mapas de bits en SovraChain, uno de revocación y otro de suspensión, creados al aprovisionar el workspace.
- Cada credencial recibe un índice (
statusListIndex) al crearse la oferta: el mismo en ambos mapas (por ejemplo,79328). - La lista se sirve como una credencial VC-JWT firmada con ES256, comprimida.
- Cada credencial SD-JWT lleva las dos URLs en su claim
credentialStatus, así que un verificador siempre sabe dónde mirar. - Si la lista del workspace se llena, crear ofertas falla con
422 bitmap_exhausted: contactá al equipo de Sovra.
Consultar la lista de estado
Endpoint público, sin autenticación. {purpose} es revocation o suspension:
curl -s "$BASE_URL/api/v1/status/did:sovra:0xcda79e1ee5612c230a6faf68236e3679b0579bae/revocation"Responde application/jwt: un VC-JWT firmado por el emisor con la lista comprimida
adentro. Es la misma URL que aparece en statusListCredential dentro de la credencial,
y no cambia entre versiones de la API, porque las credenciales ya emitidas la llevan
adentro.
La respuesta trae ETag y Cache-Control: mandá If-None-Match para recibir
304 Not Modified cuando nada cambió.
| HTTP | Cuándo |
|---|---|
| 200 | Lista firmada. |
| 304 | Sin cambios respecto de tu If-None-Match. |
| 400 | purpose distinto de revocation / suspension. |
| 404 | El DID del emisor no existe. |
Referencia: Lista de revocación y Lista de suspensión.
Particularidades de mDoc
Para un mDoc todo funciona igual: mismos estados, endpoints y webhooks. Lo único
distinto es que un mDoc siempre vence (por defecto, al año si el esquema no define
vigencia), y al vencer falla con credential_expired sin importar su estado. Ver
Vigencia.
Dónde viaja el índice de estado en un mDoc
Un mDoc no tiene campo credentialStatus, así que el status_list_index viaja dentro
del namespace reservado io.sovra.meta.1, firmado por el emisor (ver
Esquema mDoc). Un único índice sirve para
revocación y suspensión, igual que en el credentialStatus del SD-JWT.