API de emisión¶

Emite atestaciones desde tu backend con una sola llamada, sin pasar por el Portal de Emisión o el Portal de Administración. Tu sistema se autentica ante el Verifier con su credencial de máquina, pide la emisión y elige cómo se entrega la atestación al titular.

Contrato OpenAPI de emisión SDK Java — Autenticación M2M

Estado de las funciones¶

La guía describe el contrato completo de la API. Algunas partes aún no están desplegadas: están marcadas como Próximamente en su sección y no conviene usarlas hasta que lo estén.

El flujo, en resumen¶

sequenceDiagram
    autonumber
    participant App as Tu sistema
    participant V as Verifier
    participant I as API de emisión

    App->>V: POST /verifier/oidc/token (client_credentials)
    V-->>App: access_token
    App->>I: POST /issuer/api/v1/issuances<br/>Bearer + X-Idempotency-Key
    I->>I: Comprueba tenant, poderes, tipo y datos
    alt delivery = email
        I-->>App: 200 · oferta enviada al correo del titular
    else delivery = ui
        I-->>App: 200 · credential_offer_uri
    else delivery = direct
        I-->>App: 200 · atestación firmada
    end
    Note over App,I: Location: identificador del proceso de emisión

Cada petición emite una atestación para un titular, con un modo de entrega. La respuesta incluye la cabecera Location con el identificador del proceso, que es la referencia para consultarlo o revocarlo después.

Paso 1: Obtén el token de acceso¶

Tu sistema se autentica ante el Verifier de tu tenant con el grant client_credentials y su credencial de máquina (private_key_jwt). No hay registro previo de cliente ni secreto compartido: la credencial basta, y el tenant se deduce de sus poderes.

VerifierM2MClient client = VerifierM2MClient.builder()
    .verifierUrl("https://sandbox.stg.eudistack.net/verifier")
    .privateKey(privateKey)
    .credentialJwt(machineCredentialJwt)
    .build();

AccessToken token = client.authenticate();

POST /verifier/oidc/token HTTP/1.1
Host: sandbox.stg.eudistack.net
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<identificador de tu sistema>
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<JWT firmado con la clave de la credencial de máquina>

Reutiliza el access_token hasta que caduque. Envíalo en cada llamada: Authorization: Bearer <access_token>.

Paso 2: Elige el modo de entrega¶

El campo delivery decide qué hace EUDIStack con la atestación y qué te devuelve la API. Admite un solo valor.

Con email y ui, el campo opcional grant_type decide cómo recoge el titular la atestación en su wallet: authorization_code (por defecto) o urn:ietf:params:oauth:grant-type:pre-authorized_code.

Abrir la oferta en un wallet concreto¶

Con ui, la API devuelve el credential_offer_uri con el esquema openid-credential-offer://. El dispositivo del titular lo abre con el wallet que tenga registrado para ese esquema, sea cual sea, y si no tiene ninguno el enlace no hace nada. Si quieres que la oferta la abra un wallet concreto, por ejemplo el wallet web de EUDIStack, cambia el principio del enlace por la dirección donde ese wallet recibe ofertas y deja el resto igual:

• Sustituye solo openid-credential-offer://. La consulta ?credential_offer_uri=… se conserva tal cual: ya viene codificada y no hay que volver a codificarla.
• Si construyes el enlace a partir del valor de credential_offer_uri ya decodificado, codifícalo una sola vez.
• El wallet web de EUDIStack recibe ofertas en https://<tenant>.<entorno>.eudistack.net/wallet/protocol/callback. Si el titular no ha iniciado sesión en el wallet, se le pide antes de mostrar la oferta.
• Para otro wallet, usa la dirección que documente ese wallet para recibir ofertas. OID4VCI 1.0 la llama credential_offer_endpoint y prevé que el wallet la publique en sus metadatos.
• El resultado es un enlace https normal: sirve como código QR, como botón o en un correo, y abre el wallet web aunque el titular no tenga ninguna app instalada.

const WALLET_OFFER_ENDPOINT = "https://sandbox.stg.eudistack.net/wallet/protocol/callback";

function toWalletLink(credentialOfferUri) {
  const query = credentialOfferUri.substring(credentialOfferUri.indexOf("?"));
  return WALLET_OFFER_ENDPOINT + query;
}

static final String WALLET_OFFER_ENDPOINT = "https://sandbox.stg.eudistack.net/wallet/protocol/callback";

static String toWalletLink(String credentialOfferUri) {
    String query = credentialOfferUri.substring(credentialOfferUri.indexOf('?'));
    return WALLET_OFFER_ENDPOINT + query;
}

Si renuevas la oferta, aplica la misma transformación al enlace nuevo.

Atestaciones vinculadas a una clave del titular¶

Algunos tipos de atestación exigen vinculación criptográfica al titular: la atestación queda ligada a una clave que solo él controla. Con email y ui, el wallet del titular aporta esa clave al recoger la atestación y no tienes que hacer nada.

Con direct no hay wallet de por medio, así que tienes que enviar la clave pública del titular en holder_key, en formato JWK (RFC 7517). EUDIStack no pide prueba de que el titular la controla. Una clave que incluya la parte privada se rechaza con invalid_holder_key.

Paso 3: Pide la emisión¶

POST /issuer/api/v1/issuances

Dentro de payload puedes indicar validFrom y validUntil (ISO 8601) si el tipo permite fijar la vigencia; si no, se aplica la vigencia por defecto del tipo. Próximamente.

POST /issuer/api/v1/issuances HTTP/1.1
Host: sandbox.stg.eudistack.net
Authorization: Bearer <access_token>
X-Idempotency-Key: 7d1c9f3a-2b4e-4c8a-9f10-5e6d7a8b9c01
Content-Type: application/json

{
  "credential_configuration_id": "learcredential.employee.w3c.4",
  "delivery": "email",
  "email": "titular@empresa.example",
  "payload": { "...": "atributos según el esquema del tipo" }
}

HTTP/1.1 200 OK
Location: /api/v1/issuances/0b6f1d2e-8c4a-4b1f-9e2d-7a5c3f8e1b90
Content-Type: application/json

{ "responses": [ { "channel": "email", "status": 200 } ] }

{
  "credential_configuration_id": "learcredential.employee.w3c.4",
  "delivery": "ui",
  "grant_type": "urn:ietf:params:oauth:grant-type:pre-authorized_code",
  "email": "titular@empresa.example",
  "payload": { "...": "atributos según el esquema del tipo" }
}

{
  "responses": [
    {
      "channel": "ui",
      "status": 200,
      "body": { "credential_offer_uri": "openid-credential-offer://?credential_offer_uri=https%3A%2F%2F..." }
    }
  ]
}

{
  "credential_configuration_id": "learcredential.machine.sd.1",
  "delivery": "direct",
  "email": "responsable@empresa.example",
  "holder_key": {
    "kty": "EC",
    "crv": "P-256",
    "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
    "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
  },
  "payload": { "...": "atributos según el esquema del tipo" }
}

{
  "responses": [
    {
      "channel": "direct",
      "status": 200,
      "body": { "signed_credential": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImRjK3NkLWp3dCJ9...~WyJzYWx0Ii...~" }
    }
  ]
}

Guarda el identificador de Location junto al registro del titular en tu sistema: es la referencia para consultar o revocar la atestación.

Renovar la oferta¶

Una oferta de credencial caduca a los 10 minutos. Si el titular no la ha abierto a tiempo, pide una nueva para el mismo proceso, sin crear otra emisión:

POST /issuer/api/v1/issuances/{id}/credential-offer

{id} es el identificador del proceso que devolvió la emisión en Location. La petición no lleva cuerpo. EUDIStack crea una oferta nueva con el mismo grant, anula la anterior y la entrega con el modo de entrega del proceso:

Solo se puede renovar mientras el proceso está en borrador (DRAFT), es decir, mientras el titular no ha recogido la atestación. En otro estado, o si el modo es direct, se rechaza con 409 offer_not_renewable. Un proceso que no existe o que está fuera de tu ámbito recibe 404 issuance_not_found.

Con ui, esto te permite mostrar siempre una oferta vigente: cuando caduca la que muestras, pide otra y sustituye el código QR. Cuando el titular recoge la atestación, la renovación devuelve offer_not_renewable: deja de renovar.

Reintentos e idempotencia¶

Envía siempre la cabecera X-Idempotency-Key con un valor único por emisión, por ejemplo un UUID generado al preparar la petición, y reutilízalo en los reintentos de esa misma emisión. Así puedes reintentar tras un corte de red o un timeout sin emitir dos veces.

Mientras la idempotencia sea parcial, no lances dos peticiones con la misma clave a la vez y no reutilices una clave para una emisión distinta.

Errores¶

Los errores se devuelven como application/problem+json (RFC 9457). Programa tu lógica sobre type, que es un código estable, no sobre title ni detail. Una petición rechazada no deja nada creado.

{
  "type": "payload_validation_error",
  "title": "Payload validation error",
  "status": 400,
  "detail": "The payload does not match the schema of learcredential.machine.sd.1",
  "instance": "/api/v1/issuances",
  "violations": [ { "field": "payload.mandatee.serviceName", "message": "is required" } ]
}

Referencia completa¶

El contrato completo de la API de emisión, con todos los campos, respuestas y códigos de error, está en la referencia de la API del Issuer.