Issuance API¶

Issue attestations from your backend with a single call, without going through the Issuance Portal or the Administration Portal. Your system authenticates to the Verifier with its machine credential, requests the issuance and chooses how the attestation is delivered to the holder.

Issuance OpenAPI contract Java SDK — M2M authentication

Feature status¶

This guide describes the full API contract. Some parts are not deployed yet: they are marked Coming soon in their section and should not be used until they are.

The flow, in short¶

sequenceDiagram
    autonumber
    participant App as Your system
    participant V as Verifier
    participant I as Issuance API

    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: Checks tenant, powers, type and data
    alt delivery = email
        I-->>App: 200 · offer sent to the holder email
    else delivery = ui
        I-->>App: 200 · credential_offer_uri
    else delivery = direct
        I-->>App: 200 · signed attestation
    end
    Note over App,I: Location: issuance process identifier

Each request issues one attestation for one holder, with one delivery mode. The response includes the Location header with the process identifier, which is the reference to query or revoke it later.

Step 1: Get the access token¶

Your system authenticates to your tenant's Verifier with the client_credentials grant and its machine credential (private_key_jwt). There is no client pre-registration and no shared secret: the credential is enough, and the tenant is derived from its powers.

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=<your system identifier>
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<JWT signed with the machine credential key>

Reuse the access_token until it expires. Send it on every call: Authorization: Bearer <access_token>.

Step 2: Choose the delivery mode¶

The delivery field decides what EUDIStack does with the attestation and what the API returns. It takes a single value.

With email and ui, the optional grant_type field decides how the holder collects the attestation in their wallet: authorization_code (default) or urn:ietf:params:oauth:grant-type:pre-authorized_code.

Open the offer in a specific wallet¶

With ui, the API returns the credential_offer_uri with the openid-credential-offer:// scheme. The holder's device opens it with whatever wallet is registered for that scheme, and if there is none the link does nothing. If you want a specific wallet to open the offer, for example the EUDIStack web wallet, replace the start of the link with the address where that wallet receives offers and keep the rest as is:

• Replace only openid-credential-offer://. Keep the ?credential_offer_uri=… query as is: it is already encoded and must not be encoded again.
• If you build the link from the decoded credential_offer_uri value, encode it exactly once.
• The EUDIStack web wallet receives offers at https://<tenant>.<environment>.eudistack.net/wallet/protocol/callback. If the holder is not signed in to the wallet, they are asked to sign in before the offer is shown.
• For another wallet, use the address that wallet documents for receiving offers. OID4VCI 1.0 calls it credential_offer_endpoint and expects the wallet to publish it in its metadata.
• The result is a regular https link: it works as a QR code, a button or in an email, and opens the web wallet even if the holder has no app installed.

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;
}

If you renew the offer, apply the same transformation to the new link.

Attestations bound to a holder key¶

Some attestation types require cryptographic holder binding: the attestation is bound to a key that only the holder controls. With email and ui, the holder's wallet provides that key when it collects the attestation, and you do nothing.

With direct there is no wallet involved, so you must send the holder's public key in holder_key, as a JWK (RFC 7517). EUDIStack does not ask for proof that the holder controls it. A key that includes the private part is rejected with invalid_holder_key.

Step 3: Request the issuance¶

POST /issuer/api/v1/issuances

Inside payload you can set validFrom and validUntil (ISO 8601) if the type allows setting the validity; otherwise the type's default validity applies. Coming soon.

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": "holder@company.example",
  "payload": { "...": "attributes per the type schema" }
}

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": "holder@company.example",
  "payload": { "...": "attributes per the type schema" }
}

{
  "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": "owner@company.example",
  "holder_key": {
    "kty": "EC",
    "crv": "P-256",
    "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
    "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
  },
  "payload": { "...": "attributes per the type schema" }
}

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

Store the Location identifier with the holder's record in your system: it is the reference to query or revoke the attestation.

Renew the offer¶

A credential offer expires after 10 minutes. If the holder has not opened it in time, request a new one for the same process, without creating another issuance:

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

{id} is the process identifier returned by the issuance in Location. The request has no body. EUDIStack creates a new offer with the same grant, voids the previous one and delivers it with the process delivery mode:

You can only renew while the process is a draft (DRAFT), that is, while the holder has not collected the attestation. In any other state, or if the mode is direct, it is rejected with 409 offer_not_renewable. A process that does not exist or is outside your scope gets 404 issuance_not_found.

With ui, this lets you always show a valid offer: when the one you show expires, request another and replace the QR code. Once the holder collects the attestation, renewal returns offer_not_renewable: stop renewing.

Retries and idempotency¶

Always send the X-Idempotency-Key header with a unique value per issuance, for example a UUID generated when preparing the request, and reuse it when retrying that same issuance. This lets you retry after a network cut or a timeout without issuing twice.

While idempotency is partial, do not send two requests with the same key at the same time, and do not reuse a key for a different issuance.

Errors¶

Errors are returned as application/problem+json (RFC 9457). Build your logic on type, which is a stable code, not on title or detail. A rejected request leaves nothing created.

{
  "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" } ]
}

Full reference¶

The full issuance API contract, with every field, response and error code, is in the Issuer API reference.