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"

format

The system supports the following credential formats:

type	Resulting credential
SD_JWT_VC	IETF SD-JWT VC
MDOC	ISO mdoc
JSON_LD_BBSPLUS	W3C VCDM 2.0 with BBS+ Data Integrity proof
JSON_LD_CLASSIC	W3C VCDM 2.0 with Data Integrity proof
SD_JWT	W3C VCDM 2.0 with enveloping SD-JWT proof
JWT	W3C VCDM 2.0 with enveloping JWT proof
PHYSICAL_CARD	W3C VC Barcodes (verification only)

format params

Name	Type	Default	Description
leeway	number	undefined	Tolerance allowed, in seconds, in time and date variance between issuer and holder.
msoExpiresIn	number	undefined	The time, in seconds, after which an mdoc can no longer be validated; cannot use fractions of a second.
msoExpectedUpdateIn	number	undefined	The time, in seconds, after which the issuer expects the wallet to request a new MSO for an mdoc.
msoMinimumRefreshTime	number	undefined	The minimum time, in seconds, that a wallet must wait before a new MSO can be returned.
embedLayoutProperties	boolean	false	If true, credential design properties are embedded in the metadata field of schemas.
allowedContexts	url	See the list.	The list of allowed @contexts, if one has been specified.
swiyuMode	boolean	false	If true, credential formatting is adjusted to interoperate with the Swiss e-ID "swiyu" Public Beta.

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:

• https://www.w3.org/ns/credentials/v2
• https://www.w3.org/2018/credentials/v1
• https://w3c.github.io/vc-bitstring-status-list/contexts/v1.jsonld
• https://w3id.org/security/data-integrity/v2

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

issuanceProtocol

The system supports the following issuance protocols:

type	Description
OPENID4VCI_DRAFT13	OpenID for Verifiable Credential Issuance - draft 13 (ID-1)
OPENID4VCI_DRAFT13_SWIYU	OID4VCI - draft 13, adjusted to interoperate with the Swiss e-ID "swiyu" Public Beta

issuanceProtocol params

Name	Type	Default	Description
preAuthorizedCodeExpiresIn	number	undefined	Expiration time, in seconds, for code authorizing wallet to obtain credentials.
tokenExpiresIn	number	undefined	Expiration time, in seconds, for an access token issued to a wallet.
refreshExpiresIn	number	undefined	Expiration time, in seconds, for a refresh token issued to a wallet.
enabled	boolean	true	Set to false to disable issuance via OID4VCI.
redirectUri.enabled	boolean	false	Set to false to disable setting a redirect URI during credential creation.
redirectUri.allowedSchemes	string	undefined	List 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.
urlScheme	string	openid-credential-offer	Specify the credential offer URL scheme.
private.rejectionIdentifier.didMethod	string	undefined	For wallets: specify a DID method by configuration instance name to enable generation of temporary identifiers when rejecting an issuance offer.
private.rejectionIdentifier.keyAlgorithm	string	undefined	For wallets: specify a key algorithm by configuration instance name (for example ECDSA) to enable generation of temporary identifiers when rejecting an issuance offer.

verificationProtocol

The system supports the following verification protocols:

type	Description
OPENID4VP_DRAFT20	OpenID for Verifiable Presentations - draft 20
OPENID4VP_DRAFT20_SWIYU	OID4VP - draft 20, adjusted to interoperate with the Swiss e-ID "swiyu" Public Beta
OPENID4VP_DRAFT25	OpenID for Verifiable Presentations - draft 25
ISO_MDL	ISO/IEC 18013-5:2021
SCAN_TO_VERIFY	Verifiable Credential Barcodes v0.7

verificationProtocol params

All parameters apply only to instances of OID4VP:

Name	Type	Default	Description
useRequestUri	boolean	false	If 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.
enabled	boolean	true	Set to false to disable verification via OID4VCP.
redirectUri.enabled	boolean	true	Set to false to disable setting a redirect URI during proof request creation.
redirectUri.allowedSchemes	string	undefined	List 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.
urlScheme	openid4vp | mdoc-openid4vp	openid4vp	For an ISO mdoc instance of the OID4VC exchange, use mdoc-openid4vp.
x509CaCertificate	string	undefined	List of Certificate Authority (CA) certificates used to validate verifier authenticity. Any verifier must present a certificate that is signed by one of these trusted CAs. Connection attempts from verifiers with certificates signed by unlisted CAs will be automatically rejected.
verifier.supportedClientIdSchemes	verifier_attestation | redirect_uri | did | x509_san_dns	verifier_attestation | redirect_uri | did	List 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.supportedClientIdSchemes	verifier_attestation | redirect_uri | did | x509_san_dns	verifier_attestation | redirect_uri | did	List of all Client ID Schemes that can be used by the wallet during verification.

revocation

The system supports the following revocation methods:

type	Description
LVVC	Linked Validity Verifiable Credentials
BITSTRINGSTATUSLIST	Bitstring Status List
TOKENSTATUSLIST	Token Status List
MDOC_MSO_UPDATE_SUSPENSION	Suspension for mdoc credentials
NONE	No revocation method; issued credentials cannot be revoked and remain valid indefinitely

revocation params

Name	Type	Default	Description
format	JWT	null	For BITSTRINGSTATUSLIST, encode the list as a JWT.
private.credentialExpiry	number	null	For LVVC, the time, in seconds, after which an issued LVVC expires.
private.minimumRefreshTime	number	null	For LVVC, the time, in seconds, after which a wallet can request a new LVVC.

identifier

Use this object to enable or disable the use of different types of identifiers. Create an instance of each kind and use the enabled flag.

Type	Description
DID	DID methods
CERTIFICATE	X.509 certificates
KEY	Key algorithms

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

The system supports the following DID methods:

Type	Description
WEB	did:web
KEY	did:key
JWK	did:jwk
WEBVH	did:webvh (formerly did:tdw)

did params

Name	Type	Default	Description
keys.min	number	undefined	Sets the minimum number of keys that must be specified for a DID.
keys.max	number	undefined	Sets the maximum number of keys allowed for a DID.
keys.authentication	number	undefined	Use .min and .max to set allowable range of keys for the authentication verification method.
keys.assertionMethod	number	undefined	Use .min and .max to set allowable range of keys for the assertion method verification method.
keys.keyAgreement	number	undefined	Use .min and .max to set allowable range of keys for the key agreement verification method.
keys.capabilityInvocation	number	undefined	Use .min and .max to set allowable range of keys for the capability invocation verification method.
keys.capabilityDelegation	number	undefined	Use .min and .max to set allowable range of keys for the capability delegation verification method.
private.maxDidLogEntryCheck	number	undefined	For did:webvh, sets how many log entries the system will check during verification, starting from the most recent.
private.externalHostingUrl	string	undefined	For did:webvh, sets a custom external host for DID documents. Document uploading must still be integrated.

keyAlgorithm

The system supports the following key algorithms:

Type	Description
BBS_PLUS	BBS+ Signature Scheme
EDDSA	EdDSA (Ed25519)
ECDSA	ECDSA (ES256)
DILITHIUM	CRYSTALS-DILITHIUM (CRYDI3)

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

keyAlgorithm params

No parameters supported.

keyStorage

The system supports the following key storage types:

Type	Description
INTERNAL	Encrypted internal database.
AZURE_VAULT	Azure Key Vault.
SECURE_ELEMENT	Hardware storage for equipped mobile devices.
REMOTE_SECURE_ELEMENT	Hardware security module (HSM) for mobile devices; uses Ubiqu.

keyStorage params

Name	Type	Default	Description
private.encryption	string	undefined	For INTERNAL storage, specify the encryption key of the database.
private.vaultUrl	url	undefined	For AZURE_VAULT storage, specify the URL of the vault.
private.clientId	string	undefined	For AZURE_VAULT storage, specify the client ID.

datatype

The system supports the following data types:

Type	Description
STRING	Text values of any length. Examples: "Hello", "123abc"
NUMBER	Numeric values provided as strings. Examples: "123", "-456", "123.456"
DATE	ISO 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
FILE	Base64-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.
BOOLEAN	Case-sensitive boolean values. Only true or false are accepted.
OBJECT	Container 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.
ARRAY	Modifier that allows multiple values for a single key. Can be applied to any other datatype. See the claims object - arrays guide.

datatype params

Name	Type	Default	Description
min/max	number | date | NOW	undefined	For 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.
pattern	string	undefined	Regular expression pattern for STRING validation. Example: '^[A-Z]{2}[0-9]{6}$' for a passport number
accept	string	undefined	Array of allowed MIME types for FILE. Example: - image/jpeg - image/png
fileSize	number	undefined	Maximum allowed file size in bytes for FILE type.
encodeAsMdlPortrait	boolean	false	When true, encodes uploaded images according to ISO 18013-5 Mobile Driving License portrait specifications.
format	date | datetime	undefined	For 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 | datetime	undefined	Set which format should be used in the frontend. If a value is passed here, it must be in format.
error*	string	undefined	Custom error message displayed when validation fails. Example: "Please enter a valid passport number"
autocomplete*	boolean	false	Enables browser autocomplete suggestions for form fields.
placeholder*	string	undefined	Placeholder text shown in empty form fields. Example: "Enter your passport number"
showAs*	string	undefined	UI display mode for FILE type. Supported values: IMAGE, PDF, DOCUMENT

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

task

The system supports the following tasks:

Type	Description
HOLDER_CHECK_CREDENTIAL_STATUS	Runs 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_CHECK	Runs a check on claims data against its expireDuration. If the claims data has expired, the system deletes it.
SUSPEND_CHECK	Runs a check on suspensions with a defined duration. If the duration has passed, the credential is reactivated.
CERTIFICATE_CHECK	Runs a check on certificates in the system and updates their state accordingly.

task params

No parameters supported.

trustManagement

The system supports the following trust management models:

Type	Description
SIMPLE_TRUST_LIST	Procivis Trust Registry

trustManagement params

Name	Type	Default	Description
enablePublishing	boolean	false	If 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

The system supports the following transport protocols:

Type	Description
HTTP	Hypertext Transfer Protocol is the request-response protocol for the World Wide Web.
BLE	Bluetooth Low Energy can be used by mobile wallets and mobile verifiers to send, request and receive proofs.
MQTT	MQTT 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.

transport params

Name	Type	Default	Description
private.brokerUrl	url	undefined	For 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:

• Verification - Proof request - transport array
• Holding - Handle invitation - transport array

cacheEntities

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

Parameter	Type	Description
cacheType	DB | IN_MEMORY	DB: Stores cached entities in the configured database for persistence. IN_MEMORY: Stores cached entities in RAM for faster access.
refreshAfter	number	Time, in seconds, after which the cache provider automatically refreshes an entry when it's retrieved.
cacheRefreshTimeout	number	Maximum time, in seconds, the system will wait when refreshing an entry before returning an error.
cacheSize	number	Maximum 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

Type	Description
STATUS_LIST_CREDENTIAL	Status 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_DOCUMENT	DID 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_CONTEXT	For 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_METADATA	SD-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_SCHEMA	SD-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_LIST	For 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.

cacheEntities params

No parameters supported.

openidProvider

This object configures OpenID Connect providers for OpenID Bridge-enabled instances of the Desk API.

Name	Type	Default	Description
enabled	boolean	true	If 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.
credentialLoginDisabled	boolean	false	If true, login to Desk with a credential is disabled. If false, users can log in to Desk with a credential.

openidProvider params

No parameters supported.

app

The system supports the following server settings:

Name	Type	Default	Description
databaseUrl	string	undefined	URL for server database.
coreBaseUrl	string	undefined	Base URL of the Core instance.
authToken	string	undefined	Authorization token for the Core API. This should be updated for security.
serverIp	string	undefined	Server address of the Core instance.
serverPort	string	undefined	Port number of the Core instance.
traceJson	boolean	undefined	Whether to enable JSON tracing information for debugging API calls.
enableExternalEndpoints	boolean	true	When enabled, allows the usage of all /ssi endpoints. In a segregated network zone environment, set this to true for the public zone deployment.
enableManagementEndpoints	boolean	false	When 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.
traceLevel	string	undefined	Controls the logging verbosity for different components using a comma-separated list of namespace=level pairs.
sentryDsn	string	undefined	DSN for Sentry error tracking integration.
sentryEnvironment	string	undefined	Specifies the environment name to attach to error reports sent to Sentry.
hideErrorResponseCause	boolean	false	When 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.
allowInsecureHttpTransport	boolean	false	When enabled, allows HTTP communication without TLS/SSL encryption. This should only be enabled in development environments or controlled internal networks.
insecureVcApiEndpointsEnabled	boolean	false	When enabled, allows /vc-api endpoints benchmarking with canivc.com.