Configuration in 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.

warning

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

Retrieve the configuration

Configuration operations

Core API | Desk API

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
  },
  "holderKeyStorage": {
    /// Flags for enabling or disabling interactions with wallets using certain key storage types
  },
  "trustManagement": {
    /// Trust management models
  },
  "cacheEntities": {
    /// Entities stored in system cache
  }
}

For most objects there are one or more configured instances. These are described here.

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.

Desk configurations

The Desk API returns some configuration entries not found in the Core API.

Permissions

The permissions entry contains a list of all system permissions, organized by category. You can use this list when you create custom roles.

Related guide: Organizations tutorial

OpenID provider

The Desk can be configured to manage OpenID Bridge, and to accept a credential for login:

"openidProvider": {
    "enabled": true,                              // OpenID provider configuration for Bridge enabled
    "credentialLoginEnabled": true,               // Log in to the Desk with credential enabled
    "usedExchangeProtocol": "OPENID4VCI_DRAFT13"  // How login credential is issued
  },

History

"history": {
    "enabled": true,                              // History tables are accessible
    "pagesEnabled": [
      "credential-schema",
      "credential",
      "proof-schema",
      "proof",
      "trust-entity",
      "did",
      "key",
      "provider",
      "identifier"
    ]
  },

Frontend

This returns information on whether certain elements are visible in the frontend:

"frontend": {
    "reissueEnabled": true,                       // The function to reissue a credential is visible
    "walletEnabled": true                         // Wallet functionality is visible
  }