Skip to main content

One Core configuration

  • All parameters are public unless noted as private
  • Nested parameters are written with periods between levels

For example:

public:
redirectUri: # "redirectUri"
enabled: # "redirectUri.enabled"
private:
encryption: # "private.encryption"

Credential formats

Set which credential formats are available and their parameters with the format object.

The system supports the following credential formats:

typeResulting credential
SD_JWT_VCIETF SD-JWT VC
MDOCISO mdoc
JSON_LD_BBSPLUSW3C VCDM 2.0 with BBS+ Data Integrity proof
JSON_LD_CLASSICW3C VCDM 2.0 with Data Integrity proof
SD_JWTW3C VCDM 2.0 with enveloping SD-JWT proof
JWTW3C VCDM 2.0 with enveloping JWT proof
PHYSICAL_CARDW3C VC Barcodes (verification only)

Parameters

NameTypeDefaultDescription
leewaynumberNoneTolerance allowed, in seconds, applied during credential validation to account for clock drift between systems. When set, credentials that are up to this many seconds before their nbf time or after their exp time will be accepted. This prevents valid credentials from being rejected due to minor timing differences between issuer and verifier systems.
msoExpiresInnumberNoneThe time, in seconds, after which an mdoc can no longer be validated; cannot use fractions of a second.
msoExpectedUpdateInnumberNoneThe time, in seconds, after which the issuer expects the wallet to request a new MSO for an mdoc.
msoMinimumRefreshTimenumberNoneThe minimum time, in seconds, that a wallet must wait before a new MSO can be returned.
embedLayoutPropertiesbooleanfalseIf true, credential design properties are embedded in the metadata field of schemas.
allowedContextsurlSee the list.The list of allowed @contexts, if one has been specified.
swiyuModebooleanfalseIf true, credential formatting is adjusted to interoperate with the Swiss e-ID "swiyu" Public Beta. For use with SD_JWT_VC.

allowedContexts

To protect a JSON-LD Data Integrity proof from post-issuance manipulation via @context manipulation, Procivis One filters all JSON-LD credentials against an allow list.

The system checks the contexts during the verification process, only allowing the context defined by the schema plus any contexts in the allowedContexts params. If a presentation contains any additional context it will be invalidated.

If no value is entered in the allowedContexts param, the system defaults to allowing the following contexts:

If any value is entered in the allowedContexts param, the default values no longer apply and must be added to be allowed.

Issuance protocols

Set which issuance protocols are available with the issuanceProtocol object.

The system supports the following issuance protocols:

typeDescription
OPENID4VCI_DRAFT13OpenID for Verifiable Credential Issuance - draft 13 (ID-1)
OPENID4VCI_DRAFT13_SWIYUOID4VCI - draft 13, adjusted to interoperate with the Swiss e-ID "swiyu" Public Beta

Parameters

NameTypeDefaultDescription
preAuthorizedCodeExpiresInnumberNoneExpiration time, in seconds, for code authorizing wallet to obtain credentials.
tokenExpiresInnumberNoneExpiration time, in seconds, for an access token issued to a wallet.
refreshExpiresInnumberNoneExpiration time, in seconds, for a refresh token issued to a wallet.
enabledbooleantrueSet to false to disable issuance via OID4VCI.
enableCredentialPreviewbooleantrueBy default the system includes preview values of credential offers during issuance. Set this to false to disable previews.
redirectUri.enabledbooleanfalseSet to false to disable setting a redirect URI during credential creation.
redirectUri.allowedSchemesstringNoneList of URI schemes (for example https or myapp) allowed for redirect URIs during credential creation. If empty or not configured, all redirect URIs will be rejected.
urlSchemestringopenid-credential-offerSpecify the credential offer URL scheme.
private.rejectionIdentifier.didMethodstringNoneFor wallets: specify a DID method by configuration instance name to enable generation of temporary identifiers when rejecting an issuance offer.
private.rejectionIdentifier.keyAlgorithmstringNoneFor wallets: specify a key algorithm by configuration instance name (for example ECDSA) to enable generation of temporary identifiers when rejecting an issuance offer.

Verification protocols

Set which verification protocols are available with the verificationProtocol object.

The system supports the following verification protocols:

typeDescription
OPENID4VP_DRAFT20OpenID for Verifiable Presentations - draft 20
OPENID4VP_DRAFT20_SWIYUOID4VP - draft 20, adjusted to interoperate with the Swiss e-ID "swiyu" Public Beta
OPENID4VP_DRAFT25OpenID for Verifiable Presentations - draft 25
OPENID4VP_FINAL1OpenID for Verifiable Presentations 1.0
ISO_MDLISO/IEC 18013-5:2021
SCAN_TO_VERIFYVerifiable Credential Barcodes v0.7

Parameters

All parameters apply only to instances of OID4VP:

NameTypeDefaultDescription
useRequestUribooleanfalseIf true, the proof requests you make will use request URIs with which the wallet must make HTTP calls to fetch the request. This is recommended if using QR codes. If false, the proof request will be readable from the resulting URL without an HTTP call.
enabledbooleantrueSet to false to disable verification via OID4VCP.
redirectUri.enabledbooleantrueSet to false to disable setting a redirect URI during proof request creation.
redirectUri.allowedSchemesstringNoneList of URI schemes (for example https or myapp) allowed for redirect URIs during proof request creation. If empty or not configured, all redirect URIs will be rejected.
urlSchemeopenid4vp | mdoc-openid4vp | eudi-openid4vp | openid4vp-finalopenid4vpFor OID4VP 1.0, use openid4vp-final. For an ISO mdoc instance of the OID4VC exchange, use mdoc-openid4vp. For interop with EUDI, use eudi-openid4vp.
verifier.useDcqlbooleantrueFor OPENID4VP_DRAFT25 only, set this to false to use Presentation Exchange as the query language.
verifier.supportedClientIdSchemesverifier_attestation | redirect_uri | did | x509_san_dnsverifier_attestation | redirect_uri | didList of all Client ID Schemes that can be used for verification. If no scheme is specified via the API, the first compatible scheme from the list is used.
holder.supportedClientIdSchemesverifier_attestation | redirect_uri | did | x509_san_dnsverifier_attestation | redirect_uri | didList of all Client ID Schemes that can be used by the wallet during verification.

Verification engagement types

For mobile configurations, set which types of verification engagement are available with the verificationEngagement object.

The system supports the following device engagement types:

verificationEngagement:
QR_CODE: # Reference this for QR code device engagement
display: verificationEngagement.qrCode
order: 1
enabled: true
NFC: # Reference this for NFC device engagement
display: verificationEngagement.nfc
order: 2
enabled: true

You will reference these configuration entries when calling "Propose proof" (wallet) or "Create proof request" (verifier).

Revocation methods

Set which revocation methods are available with the revocation object.

The system supports the following revocation methods:

typeDescription
LVVCLinked Validity Verifiable Credentials
BITSTRINGSTATUSLISTBitstring Status List
TOKENSTATUSLISTToken Status List
MDOC_MSO_UPDATE_SUSPENSIONSuspension for mdoc credentials
NONENo revocation method; issued credentials cannot be revoked and remain valid indefinitely

Parameters

NameTypeDefaultDescription
formatJWTnullFor BITSTRINGSTATUSLIST, encode the list as a JWT.
private.credentialExpirynumbernullFor LVVC, the time, in seconds, after which an issued LVVC expires.
private.minimumRefreshTimenumbernullFor LVVC, the time, in seconds, after which a wallet can request a new LVVC.

Identifiers

Set which types of identifiers are available with the identifiers object.

The system supports the following identifiers:

TypeDescription
DIDDID methods
CERTIFICATEX.509 certificates
KEYKey algorithms

Create an instance of each kind and use the enabled flag. For example:

identifier:
DID:
display: 'identifier.did'
enabled: true
order: 0
CERTIFICATE:
display: 'identifier.certificate'
enabled: true
order: 1
KEY:
display: 'identifier.key'
enabled: true
order: 2

DID methods

Set which DID methods are available with the did object.

The system supports the following DID methods:

TypeDescription
WEBdid:web
KEYdid:key
JWKdid:jwk
WEBVHdid:webvh (formerly did:tdw)

Parameters

NameTypeDefaultDescription
keys.minnumberNoneSets the minimum number of keys that must be specified for a DID.
keys.maxnumberNoneSets the maximum number of keys allowed for a DID.
keys.authenticationnumberNoneUse .min and .max to set allowable range of keys for the authentication verification method.
keys.assertionMethodnumberNoneUse .min and .max to set allowable range of keys for the assertion method verification method.
keys.keyAgreementnumberNoneUse .min and .max to set allowable range of keys for the key agreement verification method.
keys.capabilityInvocationnumberNoneUse .min and .max to set allowable range of keys for the capability invocation verification method.
keys.capabilityDelegationnumberNoneUse .min and .max to set allowable range of keys for the capability delegation verification method.
private.maxDidLogEntryChecknumberNoneFor did:webvh, sets how many log entries the system will check during verification, starting from the most recent.
private.externalHostingUrlstringNoneFor did:webvh, sets a custom external host for DID documents. Document uploading must still be integrated.

Key algorithms

Set which key algorithms are available with the keyAlgorithm object.

The system supports the following key algorithms:

TypeDescription
BBS_PLUSBBS+ Signature Scheme
EDDSAEdDSA (Ed25519)
ECDSAECDSA (ES256)
DILITHIUMCRYSTALS-DILITHIUM (CRYDI3)

When creating your configuration, you must use these values as the instance name. There is no type for key algorithms.

Parameters

No parameters supported.

Key storage types

Set which key storage types are available with the keyStorage object.

The system supports the following key storage types:

TypeDescription
INTERNALEncrypted internal database.
AZURE_VAULTAzure Key Vault.
SECURE_ELEMENTHardware storage for equipped mobile devices.
REMOTE_SECURE_ELEMENTHardware security module (HSM) for mobile devices; uses Ubiqu.

Parameters

NameTypeDefaultDescription
private.encryptionstringNoneFor INTERNAL storage, specify the encryption key of the database.
private.vaultUrlurlNoneFor AZURE_VAULT storage, specify the URL of the vault.
private.clientIdstringNoneFor AZURE_VAULT storage, specify the client ID.

Holder key storage types

For issuers and verifiers, set which types of key storage wallets can use to interact with your system with the holderKeyStorage object.

For issuers and verifiers: use this entry to enable or disable interactions with wallets using particular kinds of key storage.

ValueDescription
SOFTWAREEnables interaction with wallets that use SOFTWARE key storage.
HARDWAREEnables interaction with wallets that use HARDWARE key storage.
REMOTE_SECURE_ELEMENTEnables interaction with wallets that use REMOTE_SECURE_ELEMENT key storage.

These settings directly impact credential schemas with an associated walletStorageType and proof schemas that use credential schemas with an associated walletStorageType. For example:

holderKeyStorage:
REMOTE_SECURE_ELEMENT:
display: 'holderKeyStorage.remoteSecureElement'
order: 20
enabled: false

With this configuration, the system would not allow:

  • The creation of new credential or proof schemas with a walletStorageType of "type": "REMOTE_SECURE_ELEMENT".
  • Credential creation or proof request that uses a previously existing schema of such walletStorageType.

Data types

Set how data types are validated with the datatype object.

The system supports the following data types:

TypeDescription
STRINGText values of any length. Examples: "Hello", "123abc"
NUMBERNumeric values provided as strings. Examples: "123", "-456", "123.456"
DATEISO 8601 formatted dates and/or RFC 3339 formatted datetimes, depending on the mandatory format param.
Supports min and max parameters in YYYY-MM-DD format for date range validation. Example: min: 2024-01-01
FILEBase64-encoded files using Data URL format:
data:[MIME type];base64,[encoded data]
Example: data:image/png;base64,iVBORw0KGgoAAAA...
File types can be restricted using the accept parameter. If not specified, all file types are allowed.
BOOLEANCase-sensitive boolean values. Only true or false are accepted.
OBJECTContainer type for nested data structures. Can hold any other supported datatype, including other objects. Used for creating hierarchical claim structures. See the claims object - nested claims guide.
ARRAYModifier that allows multiple values for a single key. Can be applied to any other datatype. See the claims object - arrays guide.

Parameters

NameTypeDefaultDescription
min/maxnumber | date | NOWNoneFor NUMBER: Sets the minimum/maximum allowed numeric value
For DATE: Sets the earliest/latest allowed date. Use "NOW" to represent the current date or date-time.
patternstringNoneRegular expression pattern for STRING validation.
Example: '^[A-Z]{2}[0-9]{6}$' for a passport number
acceptstringNoneArray of allowed MIME types for FILE.
Example:
- image/jpeg
- image/png
fileSizenumberNoneMaximum allowed file size in bytes for FILE type.
encodeAsMdlPortraitbooleanfalseWhen true, encodes uploaded images according to ISO 18013-5 Mobile Driving License portrait specifications.
formatdate | datetimeNoneFor DATE: choose whether to use and accept date (example: 2024-01-22) or datetime (example: "2024-01-22T15:57:53.123456Z") or both.
preferredFormat*date | datetimeNoneSet which format should be used in the frontend. If a value is passed here, it must be in format.
error*stringNoneCustom error message displayed when validation fails.
Example: "Please enter a valid passport number"
autocomplete*booleanfalseEnables browser autocomplete suggestions for form fields.
placeholder*stringNonePlaceholder text shown in empty form fields.
Example: "Enter your passport number"
showAs*stringNoneUI display mode for FILE type. Supported values: IMAGE, PDF, DOCUMENT

* UI-only parameters passed to the frontend without backend validation.

Regular tasks

Set which tasks can be run at /api/task/v1/run with the task object.

The system supports the following tasks:

TypeDescription
HOLDER_CHECK_CREDENTIAL_STATUSRuns a check on the status of held credentials, and updates accordingly. Pass organisationId: UUID in the params to specify the organization to check.
RETAIN_PROOF_CHECKRuns a check on claims data against its expireDuration. If the claims data has expired, the system deletes it.
SUSPEND_CHECKRuns a check on suspensions with a defined duration. If the duration has passed, the credential is reactivated.
CERTIFICATE_CHECKRuns a check on certificates in the system and updates their state accordingly.

Trust management

Set which trust management models are available with the trustManagement object.

The system supports the following trust management models:

TypeDescription
SIMPLE_TRUST_LISTProcivis Trust Registry

Parameters

NameTypeDefaultDescription
enablePublishingbooleanfalseIf true the Core instance is a publisher of trust anchors. If false it only consumes or updates a trust anchor managed by the Core instance that publishes.

Transport protocols

Set which protocols are available for exchanging credentials with the transport object.

The system supports the following transport protocols:

TypeDescription
HTTPHypertext Transfer Protocol is the request-response protocol for the World Wide Web.
BLEBluetooth Low Energy can be used by mobile wallets and mobile verifiers to send, request and receive proofs.
MQTTMQTT is a publish-subscribe network protocol for device communication, and can be used by mobile wallets and mobile verifiers to send, request and receive proofs.

Parameters

NameTypeDefaultDescription
private.brokerUrlurlNoneFor MQTT, specify the broker server for publishing and subscribing.

Transport order

For systems with multiple transport protocols enabled, use the order to set fallback preferences for which transport protocol to use.

The transport protocol to use in any given interaction can be specified at the beginning of the interaction. When this is not fully specified, the order of protocols in the configuration becomes a fallback value for determining which to use.

See the relevant transport object guide for how the system determines which protocol to use:

System cache

Set which entities are stored and the system cache and how memory is handled with the cacheEntities object.

The Core uses a caching layer to hold certain entities in temporary storage. This optimizes the system to reduce the volume of HTTP calls and enables mobile devices, both wallets and mobile verifiers, to use stored entities where internet connections are intermittent.

How caching works

For those entities managed through the cache, the cache provider retrieves one of: a cached version of the entity, a new version of the entity, or an error.

When retrieving an entity, the system checks the cache first. If the entity is in the cache and the time since it was created has not exceeded the refreshAfter time, the cache provider retrieves the cached entity.

If the age of the cached entity is greater than the refreshAfter value, the system attempts to refresh the cache entry. If the cache entry is successfully updated, this new entity is retrieved. If the refresh fails, the cache provider returns the existing cached entity unless its age has exceeded the value of cacheRefreshTimeout, in which case it returns an error.

The cache provider maintains a maximum cacheSize by deleting the entry with the fewest retrievals; in cases of entries with an equal number of retrievals, the system deletes the oldest entries.

Cache configuration

The settings of the cache provider determine how these entities are managed. Each entry in the cache provider follows a similar pattern:

cacheEntities:
ENTITY_TYPE:
cacheType: DB
refreshAfter: 86400
cacheRefreshTimeout: 172800
cacheSize: 1000
ParameterTypeDescription
cacheTypeDB | IN_MEMORYDB: Stores cached entities in the configured database for persistence.
IN_MEMORY: Stores cached entities in RAM for faster access.
refreshAfternumberTime, in seconds, after which the cache provider automatically refreshes an entry when it's retrieved.
cacheRefreshTimeoutnumberMaximum time, in seconds, the system will wait when refreshing an entry before returning an error.
cacheSizenumberMaximum number of entries that can be stored in the cache at one time.

Prune the cache

Cache entries can be deleted to force the system to retrieve external resources during the next retrieval. This can be helpful for testing purposes.

Use the DELETE method on the /api/cache/v1 endpoint, specifying in an array which of the cache entities to prune. If no cache entities are passed, the entire cache is pruned.

Force a refresh

When a wallet checks the revocation status of a held credential and that credential uses a list-based revocation method, the system normally calls into the cache to retrieve both the signed list containing the credential's status and the DID document containing the public key used to sign the list.

In order to get fresh credential validity information, use the forceRefresh parameter during revocation check. The system will then attempt to fetch the resources externally, returning success: false in the response if unsuccessful. If the resources are successfully fetched externally, they are inserted into the cache.

This applies to the following revocation methods:

  • BITSTRINGSTATUSLIST
  • TOKENSTATUSLIST

The Procivis One Wallet can also receive credentials that use the "Verifiable Credentials Status List 2021" revocation method. The credential validity information for these credentials is not handled by the cache.

Cached entities

TypeDescription
STATUS_LIST_CREDENTIALStatus of credentials with a status list type of revocation, including BITSTRINGSTATUSLIST and TOKENSTATUSLIST. When the signed list is accessed from the list URL, it is saved in the cache. Force a refresh to force external retrieval.
DID_DOCUMENTDID documents for DIDs resolved with a web call, such as did:web. This provides public keys for verifying signed tokens. Force a refresh to force external retrieval.
JSON_LD_CONTEXTFor W3C VCs, the context describes the structure and fields expected of credentials of that type and is used in calculating proofs. These documents are not expected to change often, if at all.
VCT_METADATASD-JWT VCs carry Type Metadata in the vct claim which can include human-readable information about the type of credential, a schema defining the structure of the credential and information on how to display the credential in the holder's wallet.

For vcts not retrievable via the HTTP GET method, type metadata can be saved as a static resource. Add a vct to the /resource/sd_jwt_vc_vcts.json file in the system repository. When the Core is initialized, the types in the file are loaded into the cache as persistent entities.
JSON_SCHEMASD-JWT VCs carry schema information, used for data validation, in schema or retrievable via the resource in schema_uri. These schemas are stored in the cache layer.

JSON schemas can be saved as a static resource. Add schemas to the /resource/sd_jwt_vc_schemas.json file in the system repository. When the Core is initialized, the types in the file are loaded into the cache as persistent entities.
TRUST_LISTFor the Procivis One Trust Registry, subscribed trust anchors are cached and incoming issuer and verifier DIDs are checked against this list to determine whether they are trusted.

Blob storage

To improve database efficiency, some data objects are stored in a separate table in the database; this increases the speed of common queries. Stored entities include:

  • Credentials
  • Proofs

Enable blob storage in the configuration:

blobStorage:
DB:
enabled: true
note

Disabling blob storage will cause application errors.

OpenID providers

Configure OpenID Connect providers for OpenID Bridge-enabled instances of the Desk API with the openidProvider object.

NameTypeDefaultDescription
enabledbooleantrueIf false, Bridge is disabled and OpenID providers cannot be added or managed. If true, Bridge is enabled and OpenID providers can be added and managed.
credentialLoginDisabledbooleanfalseIf true, login to Desk with a credential is disabled. If false, users can log in to Desk with a credential.

Enabled OID4VCI issuers

For wallets using the issuer-initiated Authorization Code Flow of OpenID4VCI, set:

  • Which issuers are enabled to offer credentials
  • The Client ID to use with each enabled issuer

with the credentialIssuer object. All parameters are required:

NameTypeDefaultDescription
public.issuerURLNoneSpecify the URL of the issuer to accept credential offers from.
private.clientIdstringNoneSpecify which client ID to use with this issuer.

For example:

credentialIssuer:
EXAMPLE_FLOW:
display:
en: Example Issuer
order: 1
enabled: true
params:
public:
issuer: https://example-issuer.com
private:
clientId: MY-WALLET

Server settings

Configure your server with the app object.

The system supports the following server settings:

NameTypeDefaultDescription
databaseUrlstringNoneURL for server database.
coreBaseUrlstringNoneBase URL of the Core instance.
authTokenstringNoneAuthorization token for the Core API. This should be updated for security.
serverIpstringNoneServer address of the Core instance.
serverPortstringNonePort number of the Core instance.
traceJsonbooleanNoneWhether to enable JSON tracing information for debugging API calls.
enableExternalEndpointsbooleantrueWhen enabled, allows the usage of all /ssi endpoints. In a segregated network zone environment, set this to true for the public zone deployment.
enableManagementEndpointsbooleanfalseWhen enabled, allows the usage of all /api endpoints. In a segregated network zone environment, set this to true for the internal zone deployment and false for the public zone deployment.
traceLevelstringNoneControls the logging verbosity for different components using a comma-separated list of namespace=level pairs.
sentryDsnstringNoneDSN for Sentry error tracking integration.
sentryEnvironmentstringNoneSpecifies the environment name to attach to error reports sent to Sentry.
hideErrorResponseCausebooleanfalseWhen enabled, strips internal error details from API error responses sent to clients. This should typically be enabled in production to avoid exposing sensitive implementation details in error messages, while disabled in development for easier debugging.
allowInsecureHttpTransportbooleanfalseWhen enabled, allows HTTP communication without TLS/SSL encryption. This should only be enabled in development environments or controlled internal networks.
enableServerInfobooleanfalseWhen enabled, allows the /health and /build-info endpoints.
enableMetricsbooleanfalseWhen enabled, allows the /metrics endpoint.
insecureVcApiEndpointsEnabledbooleanfalseWhen enabled, allows /vc-api endpoints benchmarking with canivc.com.