Skip to main content

Identifiers

Learn how to work with identifiers.

No matter your role in a credential-based interaction, you need an identifier. This page explains how the system uses identifiers and how to create the identifiers you need for your use cases.

Identifiers in Procivis One​

The type of identifier you need is likely determined by the ecosystem in which you interact, for example: did:webvh for Swiss E-ID, X.509 certificates for ISO mdoc, and DIDs and keys for IETF SD-JWT VC.

To enable you to work flexibly across different ecosystems, Procivis One uses "identifier" as an abstraction. Create the identifiers you need. When you engage in an interaction, use the identifier appropriate to that interaction.

Identifier creation workflow​

Use identifiers to represent your organization:

For issuers and verifiers with complex, multi-tenant organizations working across international borders and identity ecosystems, this could entail creating multiple identifiers of different types, for many different organizations. You can create as many identifiers for as many different organizations as you need.

For holders: the simplest setup is to create one identifier of each type needed. For example, if you are receiving credentials in an ecosystem that uses DIDs and keys, initialize the wallet with a DID and a key pair for signing.

Enabling types of identifiers​

Use the identifier configuration object to enable or disable types of identifiers. This determines which types of identifiers are available to use in your solution.

Related guide: identifier reference

Choosing types of identifiers​

Your required identifiers depend on the ecosystem in which you operate. As a shortcut, identify the credential format you will use. Retrieve the configuration through the API and check that format's capabilities.

For example, suppose you know you will be working with IETF SD-JWT VC and your configuration includes this:

"format": {
  "SD_JWT_VC": {
      "type": "SD_JWT_VC",
      "display": "format.sdjwt_vc",
      "order": 200,
      "capabilities": {
        "issuanceIdentifierTypes": [        // List of compatible identifier types for issuing this format
          "KEY",
          "DID"
        ],
        "verificationIdentifierTypes": [    // List of compatible identifier types for verifying this format
          "KEY",
          "DID"
        ],
      },
    },
},

Then you know you can use keys or DIDs as an identifier, or both, but not certificates.

Identifiers and trust management​

Trust management is an important layer of any digital identity ecosystem. Mechanisms of trust management are still in development for most ecosystems, but generally it involves a registry of identifiers for trusted ecosystem participants.

You can add your identifiers to the Procivis Trust Registry now. As ecosystems harden, new trust management solutions will be added.

Related guide: Trust management

Supported identifiers​

All identifiers in the system are one of the following type.

Keys​

Keys can be used:

  • To create DIDs
  • To create certificates
  • Independently, as an identifier for certain credential models

Because keys can be used in different ways, use the api/key/v1 endpoint to create and manage keys. When you want to use a key as an identifier, create an identifier with the /api/identifier/v1 endpoint, referencing an existing key with the POST call.

Related guide: Keys

DIDs​

Decentralized Identifiers (DIDs) are a commonly used identifier for credential models. Use the /api/identifier/v1 endpoint to create and manage DIDs as an identifier.

Alternatively, the system has legacy DID endpoints at /api/did/v1 that can be used to create and manage DIDs. When you use the POST method on the DID endpoint, the system automatically creates an identifier.

Related guide: DIDs

Certificates​

X.509 certificates are commonly used to establish trust in identity by binding a public key to an entity through the signature of a trusted Certificate Authority (CA). To use a certificate as an identifier you start the process with the system, get a signature from a CA outside the system, then finish by uploading the signed certificate as an identifier.

Related guide: Certificates

Depracated

Previously you were required to create a DID to use a certificate (for example, a did:mdl for ISO mdoc issuance). This workaround is depracated.

Create an identifier​

An identifier consists of:

  • Identifier name
  • Organization
  • Choice of identifier

The identifier name must be unique within the organization.

Choose the identifier​

When you create an identifier, choose one and only one identifier type. The request body varies by the type of identifier you are creating. See the request body examples for each type of identifier:

{
  "name": "Example Identifier", // Mandatory identifier name
  "organisationId": "{{ORG-UUID}}", // Not required if using the Desk API
  "did": {
    "method": "WEB", // Reference the configured instance of your chosen DID method
    "name": "DID name", // Optional DID name
    "keys": {
      "authentication": ["{{KEY-UUID}}"],
      "assertionMethod": ["{{KEY-UUID}}"],
      "keyAgreement": ["{{KEY-UUID}}"],
      "capabilityInvocation": ["{{KEY-UUID}}"],
      "capabilityDelegation": ["{{KEY-UUID}}"]
    }
  }
}

Use an identifier​

When you engage in an interaction, use the identifier appropriate to that interaction. You select your identifier at a different stage of interactions according to your role:

Reference your chosen identifier when you create a credential. When you issue that credential, your identifier will help the wallet holder know who you are via the trust management layer, and your identifier will be directly referenced in the issued credential.

Identifier status​

The status of all identifiers in the system is representated as either ACTIVE or DEACTIVATED.

  • Keys and DIDs: all entities are active unless deactivated by the owner

  • Certificates: all entities are active unless none of the certificates in the chain are valid