Skip to main content

API reference

Every EUDIPLO instance serves its own OpenAPI specification, so the reference always matches the running version. Your backend calls the management API under /api; wallets call the protocol endpoints at the root path.

Specifications​

APISwagger UIOpenAPI JSONContents
Management API/api/docs/api/docs-jsonEverything under /api: tenants, clients, configurations, key chains, offers, sessions, lists
Protocol API/docs/docs-jsonWallet-facing OID4VCI, OID4VP and ISO 18013-7 endpoints, metadata, status and trust lists

Both are OpenAPI 3.1 documents. In Swagger UI, choose Authorize to call the management API with a client's credentials.

Path prefixes​

Management endpoints carry the /api prefix, for example POST /api/issuer/offer. Wallet-facing and public endpoints are served without it:

PathPurpose
/.well-known/...Issuer and authorization server metadata, JWKS
/issuers/{tenant}/vci/...Credential offer, credential, deferred, notification and nonce endpoints
/issuers/{tenant}/authorize/...Built-in authorization server (PAR, authorize, token, interactive)
/issuers/{tenant}/chained-as/...Chained authorization server
/issuers/{tenant}/authorization-servers/{id}/...OID4VP-based authorization servers
/issuers/{tenant}/credentials-metadata/...SD-JWT VC type metadata
/issuers/{tenant}/status-management/...Status lists
/issuers/{tenant}/trust-list/...Published trust lists
/issuers/{tenant}/.well-known/openid-federationOpenID Federation entity configuration
/presentations/{walletNonce}/oid4vp/...OID4VP request object and response endpoint
/presentations/{walletNonce}/iso-18013-7ISO 18013-7 Annex C response endpoint
/verifiers/{tenant}/oidc/...OpenID Provider: discovery, JWKS, PAR, authorize, sign-in page, token
/storage/{key}Public files such as credential logos
/healthHealth check

When you restrict network access to the management API, keep the wallet-facing paths reachable from the internet; see Web application firewall.

Authentication​

Management endpoints require a bearer token of an API client. Which client holds which roles is described in Tenants and access.

With the built-in OAuth 2.0 server (the default), request a token with the client credentials grant:

curl -X POST https://eudiplo.example.com/api/oauth2/token \
-d grant_type=client_credentials \
-d client_id=membership-backend \
-d client_secret="$CLIENT_SECRET"

The endpoint accepts the credentials in the form or JSON body or as HTTP Basic authentication. The response contains an access_token that is valid for 24 hours (expires_in: 86400) and no refresh token; send it as Authorization: Bearer <token>, and request a new one when it expires. GET /.well-known/oauth-authorization-server advertises the token endpoint for OAuth client libraries.

When OIDC is set, for example to use Keycloak, /api/oauth2/token is disabled and tokens come from the external provider.

This includes the session event stream GET /api/session/{id}/events, which does not accept tokens in the URL. Browsers cannot set headers on an EventSource, so read the stream from your backend.

GET /api/auth/me needs no role and returns the subject, tenant and roles the backend grants for the token: with the built-in server the client's current roles, with an external provider those of the token's claims. Use it to check which tenant and roles a token resolves to.

@eudiplo/sdk-core​

@eudiplo/sdk-core is the TypeScript client for the management API. It works in Node.js 20+ and in browsers.

npm install @eudiplo/sdk-core

EudiploClient covers the common flows. It fetches and renews the token from /api/oauth2/token itself:

import { EudiploClient } from "@eudiplo/sdk-core";

const eudiplo = new EudiploClient({
baseUrl: "https://eudiplo.example.com",
clientId: process.env.EUDIPLO_CLIENT_ID!,
clientSecret: process.env.EUDIPLO_CLIENT_SECRET!,
});

const { crossDeviceUri, sessionId } = await eudiplo.createPresentationRequest({
configId: "membership-check",
});
// Show `crossDeviceUri` as a QR code (on the phone itself, open `uri`),
// then wait for a terminal status.
const session = await eudiplo.waitForSession(sessionId);
MethodPurpose
createIssuanceOffer()POST /api/issuer/offer with inline claims
createPresentationRequest()POST /api/verifier/offer
getSession(), waitForSession()Read or poll a session until it is completed, failed or expired
subscribeToSession(), waitForSessionWithSse()Follow a session over Server-Sent Events
createDcApiPresentationRequest(), submitDcApiPresentation(), verifyWithDcApi()Digital Credentials API flow in the browser

Keep clientId and clientSecret on your server. Browser code should talk to your backend, which calls EUDIPLO.

For every other endpoint, use the generated functions from @eudiplo/sdk-core/api. They are generated from the management OpenAPI specification and named after the controller method, for example sessionControllerGetSession or webhookEndpointControllerCreate:

import { client, sessionControllerGetSession } from "@eudiplo/sdk-core/api";

client.setConfig({
baseUrl: "https://eudiplo.example.com",
headers: { Authorization: `Bearer ${accessToken}` },
});

const { data: session } = await sessionControllerGetSession({
path: { id: sessionId },
});

EudiploClient authenticates only against the built-in OAuth 2.0 server. With an external OIDC provider, obtain the token yourself and use the generated functions as shown above.