API Reference

Endpoints for Verifiable Presentation exchange and credential issuance

The API is available for early access on Hedera Testnet. Contact us if you are interested in integrating or collaborating.

Endpoints

Method	Endpoint	Description
POST	/api/vp/request	Create a VP request
GET	/api/vp/request/:id	Get VP request details
GET	/api/vp/response/:id	Poll for VP response
POST	/api/vp/submit/:id	Relay endpoint (testnet only)
GET	/.well-known/openid-credential-issuer	OID4VCI issuer metadata
POST	/token	OID4VCI token endpoint
POST	/credential	OID4VCI credential issuance
GET	/api/health	Health check

---

Verifiable Presentations (VP)

These endpoints implement the OID4VP flow for requesting and receiving user credentials. See Verification Flows for the full integration guide.

Create a VP request

POST /api/vp/request

Create a new presentation request specifying what credentials and constraints you require.

Field	Type	Required	Description
requestedCredentials	array	Yes	Credential types and constraints to request
requestedCredentials[].type	string	Yes	Credential type (e.g. PersonhoodCredential)
requestedCredentials[].constraints.minScore	number	No	Minimum personhood score (0-100)
verifierDid	string	No	Your application’s DID

Returns the request ID, a challenge nonce, an openid4vpUri for QR code encoding, a shareUrl web fallback, expiration time, and status.

---

Get VP request details

GET /api/vp/request/:id

Retrieve the details of an existing VP request. Returns 404 if not found. Status is automatically updated to expired after 15 minutes.

---

Poll for VP response

GET /api/vp/response/:id

Poll this endpoint to check if the credential holder has submitted their presentation. Returns pending, submitted (with the full presentation payload), or expired.

---

Relay endpoint (testnet)

POST /api/vp/submit/:id

Forwards presentations for demo and testing purposes. In production, the wallet submits directly to the verifier per the OID4VP specification.

---

Credential Issuance (OID4VCI)

These endpoints follow the OID4VCI specification for wallet-based credential issuance.

Method	Endpoint	Description
GET	/.well-known/openid-credential-issuer	Issuer metadata discovery
POST	/token	Token endpoint for credential issuance
POST	/credential	Credential issuance endpoint

These endpoints are used by compatible wallet applications to receive Verifiable Credentials from the Soverage Gateway.

---

Health check

GET /api/health

Returns server status. Use this to verify connectivity before making other API calls.

---

Try it

The demo is a fully working example of VP-based access control. It includes configurable requirements, QR code generation, VP polling, and code snippets for frontend and backend integration. Use it as a starting point for your own integration.