Skip to main content

Identifiers Overview

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: X.509 certificates for ISO mDOC and Access Certificates, keys for IETF SD-JWT VC, and DIDs for certain credential formats.

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 system automatically generates dedicated key pairs for each credential issuance, so identifier management is typically not required for holding workflows. See the example Wallet Workflow with the SDK for an example.

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.

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). Certificates are the required identifier type for ISO mDOC credential issuance.

To use a certificate as an identifier, you generate a Certificate Signing Request (CSR) using the system, obtain a signature from a CA (either external or your own CA infrastructure), then import the signed certificate as an identifier.

Related guide: Certificates

Certificate Authorities​

Certificate Authority (CA) identifiers enable you to sign and issue certificates. You can either import an existing CA certificate chain or create a self-signed root CA directly through the system.

CA identifiers are used for issuing Access Certificates as required by EUDI wallet specifications, and can also be used to sign X.509 certificates through the signature endpoint for other certificate-based workflows.

Related guide: Certificates

Keys​

Keys can be used:

  • To create certificates
  • Independently, as an identifier for certain credential models (like IETF SD-JWT VC)

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) can be used as identifiers for certain credential formats. 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

Creating identifiers​

To create an identifier, use the POST /identifier endpoint with your chosen identifier type. Each identifier consists of a name, organization, and the specific identifier configuration.

See the type-specific guides for detailed creation instructions:

  • Certificates - For certificate and CA identifiers
  • Keys - For key identifiers
  • DIDs - For DID identifiers

Using identifiers​

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