Configuration in the API

Learn how to retrieve and read the configuration via the API

Reading and understanding your system configuration is important for working with the API. This guide explains how to understand a configuration and how to use this knowledge to build a successful integration.

How it works

The system configuration comes from a set of .yml files and environment variables which are passed to the program when the server is started. These elements determine how the system operates, including:

• Which technologies and standards are available to use
• Configuration parameters for each technology and standard
• How each technology and standard is referenced

Once the server is started, you can retrieve the configuration via the API to read and understand how your system operates.

What's exposed in the API

The configuration retrieved from the API includes the major components and parameters of your system, giving you the ability to know what's available and how to use it.

Some configuration elements are not exposed in the API, including:

• Private parameters, including:
  • Secrets, such as encryption keys and client details for HSM integrations
  • Root certificates
  • Expiry times for certain revocation methods, such as LVVC
  • Broker URLs for MQTT integrations
• Server settings for deployment

Capabilities

Once the server is started, the system generates capabilities for most configured elements of the solution. These are reports that reflect properties of elements including:

• Features and operations available
• Compatability with other elements of the solution

Capabilities are included in the configuration response and are useful for knowing what is possible with different elements of the system and for passing such information on to the frontend to inform users.

Related guide: Capabilities reference

Retrieve the configuration

Configuration operations

Core API | Desk API | SDK

Read the configuration

Start by looking for the root-level objects:

{
  "format": {
    /// Credential formats
  },
  "issuanceProtocol": {
    /// Issuance protocols
  },
  "verificationProtocol": {
    /// Verification protocols
  },
  "transport": {
    /// Transport protocols
  },
  "revocation": {
    /// Revocation methods
  },
  "did": {
    /// DID methods
  },
  "datatype": {
    /// Data types for data validation
  },
  "keyAlgorithm": {
    /// Key algorithms
  },
  "keyStorage": {
    /// Key storage methods
  },
  "trustManagement": {
    /// Trust management models
  },
  "cacheEntities": {
    /// Entities stored in system cache
  }
}

For each object there are one or more configured instances.

Here's an example format object. Look at the instance names and types:

{
  "format": {
    "JSON_LD_CLASSIC": {
      /// Instance name
      "type": "JSON_LD_CLASSIC" /// Type of technology
    },
    "PHYSICAL_CARD": {
      "type": "PHYSICAL_CARD"
    },
    "MDOC": {
      "type": "MDOC"
    },
    "SD_JWT_VC": {
      "type": "SD_JWT_VC"
    },
    "JSON_LD_BBSPLUS": {
      "type": "JSON_LD_BBSPLUS"
    },
    "JWT": {
      "type": "JWT"
    },
    "SD_JWT": {
      "type": "SD_JWT"
    }
  }
}

In the example above we have seven configured credential formats. The type represents the kind of technology while the instance name is what you reference when making API calls. See the configuration reference for a reference of all supported types.

Look at each instance to understand how it is configured. Most instances follow a similar structure:

"JSON_LD_CLASSIC": {
      "capabilities": {},
      "display": "format.jsonld_classic",
      "order": 0,
      "params": {},
      "type": "JSON_LD_CLASSIC",
      "enabled": true
    },

Display

The display field defines how the instance is displayed in the UI. It is a key which should resolve to something stored in the frontend. This can also be used to pass a map of translations.

Order

For all root-level objects except transport, the order value is passed to the frontend without interpretation to indicate the order in which instances appear in the UI.

For transport in configurations supporting more than one protocol, the order determines preferences for which transport protocol to use during exchanges where multiple transport protocols are supported.

Enabled

The enabled field is a boolean value indicating whether the instance can be used to create new entities.

For null or true: the instance can be used to create new entities.

For false: no new entities can be created but existing entities can still be used.

Params

The params are the primary means of configuring instances. See the configuration reference for a complete reference of params.

Reference the configuration

The distinction between instance name and type is important because configurations can contain multiple instances of the same type:

"datatype": {
    "DATE": {                               // Reference this
      "display": "datatype.date",
      "order": 300,
      "params": {
        "formats": [
          "date",
          "datetime"
        ]
      },
      "type": "DATE"
    },
    "BIRTH_DATE": {                         // Reference this
      "display": "datatype.birth_date",
      "order": 310,
      "params": {
        "error": {
          "de": "Bitte wählen Sie ein Datum zwischen 1900-1-1 und heute",
          "en": "Please choose a date between 1900-1-1 and today"
        },
        "formats": [
          "date",
          "datetime"
        ],
        "max": "NOW",
        "min": "1900-01-01",
        "preferredFormat": "date"
      },
      "type": "DATE"
    }
}

Make sure to reference the desired configuration instance. For example, when creating credential schemas you must specify a data type for claim validation. Using the example above, reference DATE or BIRTH_DATE, depending on the params you want to use for validation.

Capabilities reference

Warning

warning

If you modify the source code of the system, consider how the capabilities should be updated.

format

The following capabilities for credential formats are supported:

Name	Value	Description
features	SELECTIVE_DISCLOSURE	Present if the format supports selective disclosure.
features	SUPPORTS_CREDENTIAL_DESIGN	Present if the format supports embedding layoutProperties in the credential.
features	REQUIRES_SCHEMA_ID	Present if the format requires a schemaId during credential schema creation.
datatypes	[datatypes]	Lists the datatypes supported by the credential format.
allowedSchemaIds	[allowed schema IDs]	Lists the allowed schema IDs, if restricted.
selectiveDisclosure	[]	Selective disclosure not possible; when creating proof schemas with this format, all root-level claims of a credential must be present.
selectiveDisclosure	[ANY_LEVEL]	Selective disclosure is possible on claims at any level; when creating proof schemas with this format, any subset of claims can be requested.
selectiveDisclosure	[SECOND_LEVEL]	Selective disclosure is possible only on root- or second-level claims.
signingKeyAlgorithms	[key algorithm types]	Lists the key signing algorithm types supported by the credential format.
verificationKeyAlgorithms	[key algorithm types]	Lists the verifier algorithms supported by the credential format.
verificationKeyStorages	[key storage types]	Lists the key storage types verifier DIDs can use when proof schemas include this credential format.
issuanceDidMethods	[did method types]	Lists the DID methods supported by the credential format.
issuanceExchangeProtocols	[issuance protocol types]	Lists the issuance protocols usable with this credential format.
proofExchangeProtocols	[verification protocol types]	Lists the verification protocols usable with this credential format.
revocationMethods	[revocation method types]	Lists the revocation methods supported by the credential format.
forbiddenClaimNames	[strings]	Lists the disallowed claim names.
datatypes	[datatypes]	Lists the allowed datatypes.

issuanceProtocol

Name	Value	Description
didMethods	[method name]	Lists the DID methods that can be used with the issuance protocol.

verificationProtocol

Name	Value	Description
didMethods	[method name]	Lists the DID methods that can be used with the verification protocol.
supportedTransports	[transport protocol]	Lists the transport protocols that can be used with the verification protocol.

revocation

The following capabilities for revocation methods are supported:

Key	Value	Description
operations	REVOKE	Present if the method can revoke issued credentials.
	SUSPEND	Present if the method can suspend issued credentials.

did

The following capabilities for DID methods are supported:

Key	Value	Description
operations	RESOLVE	Present if the DID method supports DID document resolvability.
operations	CREATE	Present if the DID method supports DID document creation.
operations	DEACTIVATE	Present if the DID method supports DID deactivation.
keyAlgorithms	[keyAlgorithm]	Lists the key signing algorithms supported by the DID method.
methodNames	[method name]	Lists the method names supported by the DID method implementation. (did:{{method-name}}:address)
supportedUpdateKeyTypes	[keyAlgorithm]	Lists the key signing algorithms supported for updateKeys, keys which are automatically generated by the system during creation of some DID methods (for example, did:webvh).
features	SUPPORTS_EXTERNAL_HOSTING	Present if DIDs can be created and then published on an external URL.

keyAlgorithm

The following capabilities for key algorithms are supported:

Key	Value	Description
features	GENERATE_CSR	Present if the keys generated with the algorithm can be used to generate Certificate Signing Requests, for mDL issuance.

keyStorage: capabilities

The following capabilities for key storage are supported:

Key	Value	Description
algorithms	[keyAlgorithm]	Enumerates the algorithms supported by the key storage type.
security	HARDWARE or SOFTWARE	Whether the storage type is hardware- or software-based.
features	EXPORTABLE	Present if keys stored with this type can be exported/backed up.