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.

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

Creating remote identifiers​

You can create "remote" identifiers which are represented in the system but not controlled by your Procivis One deployment. This is used when adding entries to a trust list publication. Use POST /api/identifier/v1/remote to create a remote identifier.

Auto-generated identifiers​

For certain workflows, the system generates keys and identifiers on its own, without you making a direct call to create one. This includes:

  • Accepting a credential issuance without specifying an identifier
  • Accepting or refreshing a batch credential
    • The system generates a key for each batch item
  • Remote keys and identifiers
    • When you interact with others, the system creates their keys and identifiers in the database and marks these as auto-generated
    • These keys and identifiers are both auto-generated and remote
  • Creating a did:webvh
    • When you create this DID, the system creates an Ed25519 key to generate a Data Integrity proof of the DID log

Filtering​

For the /identifier and /key resources, use autogenerated and isRemote parameters to identify on the detail endpoints:

  • GET /api/identifier/v1/{id}
  • GET /api/key/v1/{id}

and to filter as a query parameter on the list endpoints:

  • GET /api/identifier/v1
  • GET /api/key/v1
note

All keys and identifiers created by the system are autogenerated, but some isRemote keys and identifiers can be created by users. See Creating remote identifiers.