Issuer Identity Registry

Getting Started with IIR Registration and Verification

Joining the Issuer Identity Registry (IIR) involves two primary processes:

1. Organization onboarding and verification — The onboarding and verification process is intended for organizational administrators and general users responsible for establishing an organization’s participation in the Credential Registry and IIR, IIR onboarding guidance is available at: https://guidance.credentialengine.org/issuer-identity-registry/
2. DID submission and validation — The DID submission process is a technical workflow typically completed by a developer or technical staff member responsible for managing the organization’s decentralized identity infrastructure. This handbook covers these topics.

DID Submission and Validation

After the organization onboarding and verification process is completed, the organization may submit one or more Decentralized Identifiers (DIDs) for validation and registration within the IIR.

The DID submission workflow:

• Confirms that the organization controls the DID
• Validates the associated verification method
• Registers the DID within the IIR infrastructure
• Enables machine-verifiable issuer identity
• Registers a Quality Assurance Action in the Credential Registry

Figure 2: Credential Engine Platform

This figure shows the flow of data with the Credential Engine platform and interactions between credential issuers, credential holders, and employers.

DID Submission Overview

This handbook provides instructions for single DID submission and bulk DID submission.

Credential Engine provides:

• Interface for submitting individual DIDs
• Command Line Interface (CLI) for submitting DID bulk submittal
• Cryptographic challenge specific to the DID submission
• Python script example for creating single or multiple DID JSON Web Tokens (JWTs)

The DID submission process verifies the DID:

• Resolves correctly using a supported DID method
• Association with the organization’s identity and is under the organization’s control
• Signed payload confirms the organization’s authority over the DID

After the organization verification is completed, the DID validation and registration workflow is accessible through the Credential Publisher under the Tools menu.

• Log in to your Credential Engine Publisher
• Navigate to “Tools” and select “Issuer Identity Registry (IIR)”

IIR Dashboard and Organization Selection

The IIR Dashboard displays registered issuers associated with the organizations connected to the authenticated user account.

Organizations approved to participate in the IIR appear within the “My Organizations” section

• The user begins by selecting the organization for DID registration.
• Organization information is automatically populated from the Credential Registry and associated account records. Auto-filled data from the Credential Registry includes the following:

Submit individual DIDs interface

Entering and Resolving DIDs

After selecting the organization, the issuer enters the DID to be registered. The IIR currently supports:

• did:web
• did:key

did:web

The did:web method is verified by resolving the organization’s DID Document from its public web domain. Requirements include:

• Public HTTPS availability
• Accessible DID Document
• Valid verification methods

did:key

The did:key method is verified using the cryptographic verification method embedded within the DID. Supported algorithm: Ed25519 (EdDSA).

Once a valid DID is entered, the system automatically:

• Resolves the DID
• Retrieves associated verification methods
• Displays available verification methods associated with the DID
• Validates the DID and shows a success message
  • Validated DIDs are published to the IIR and shown on the organization’s IIR dashboard.
  • DIDs that don’t validate show an error:
    • The did:web value is invalid.
    • The did:key could not be resolved.

Challenge Generation and Signing Workflow for Individual DID

For each verification method associated with the DID, Credential Engine generates a unique and time-sensitive challenge payload. Initially, challenges are valid for 24 hours. Credential Engine expects to decrease the challenge availability significantly once workflows are established.

Each challenge:

• Is associated with a specific verification method
• Must be signed using the corresponding private key
• Is downloaded as a JSON file for local signing

Only an entity with access to the organization’s private key can correctly sign the generated challenge.

Example challenge payload:

						{
						"challenge": "f8cea1a7-2249-44ee-a067-b12b4c99e503",
						"did": "did:web:sandbox.credentialengine.org#z6MkwYGVFm6oFReLYwoHLobjVV5PBjnaYwB9VvJahn4nAx4f",
						"aud": "https://issuerregistry.credentialengine.org",
						"iat": 1779224524,
						"exp": 1779310924
						}
					

{
 "alg": "EdDSA",
 "kid": "did:key:z6Mkj8AnYUMWcuNLPZA7dQPpsb5h8YZzzE46osn3C8QjWjyS#z6Mkj8AnYUMWcuNLPZA7dQPpsb5h8YZzzE46osn3C8QjWjyS",
 "typ": "JWT"
}

{
  "challenge": "e9dc01d2-37e0-4a84-9106-2507c8ce806d",
  "did": "did:key:z6Mkj8AnYUMWcuNLPZA7dQPpsb5h8YZzzE46osn3C8QjWjyS#z6Mkj8AnYUMWcuNLPZA7dQPpsb5h8YZzzE46osn3C8QjWjyS",
  "aud": "https://issuerregistry.credentialengine.org",
  "iat": 1779225540,
  "exp": 1779311940
}

eyJhbGciOiJFZERTQSIsImtpZCI6ImRpZDprZXk6ejZNa2o4QW5ZVU1XY3VOTFBaQTdkUVBwc2I1aDhZWnp6RTQ2b3NuM0M4UWpXanlTI3o2TWtqOEFuWVVNV2N1TkxQWkE3ZFFQcHNiNWg4WVp6ekU0Nm9zbjNDOFFqV2p5UyIsInR5cCI6IkpXVCJ9.eyJjaGFsbGVuZ2UiOiJlOWRjMDFkMi0zN2UwLTRhODQtOTEwNi0yNTA3YzhjZTgwNmQiLCJkaWQiOiJkaWQ6a2V5Ono2TWtqOEFuWVVNV2N1TkxQWkE3ZFFQcHNiNWg4WVp6ekU0Nm9zbjNDOFFqV2p5UyN6Nk1rajhBbllVTVdjdU5MUFpBN2RRUHBzYjVoOFlaenpFNDZvc24zQzhRaldqeVMiLCJhdWQiOiJodHRwczovL2lzc3VlcnJlZ2lzdHJ5LmNyZWRlbnRpYWxlbmdpbmUub3JnIiwiaWF0IjoxNzc5MjI1NTQwLCJleHAiOjE3NzkzMTE5NDB9.zv4Xk86uSPYP6hC-gRlOyDSJsyl6ztGi6Eq0WTJzyU0ajXTlPc1q5Dj_W_Gv0rOu4sVuNKXyh6_LkCuhxg7RBA

Submitting Signed Individual JWTs

After signing challenges locally, the issuer pastes each signed JWT into the corresponding field within the IIR submission interface.

As each JWT is submitted:

• The system validates the signature
• Verification status is displayed immediately
• Successfully validated JWTs are automatically saved by the system

After final submission:

• The DID is registered within the IIR along with the issuer organization data retrieved from the Credential Registry
• The validated issuer DID, along with the issuer organization data retrieved from the Credential Registry, is available through the IIR endpoints

Bulk DID Submissions

Use the CLI to support bulk DID submissions.

Select “Bulk Upload” from the organization’s IIR Dashboard. This directs the user to the GitHub script:

GitHub CLI: https://github.com/CredentialEngine/ce-cli

The GitHub repo provides instructions to run a Command Line Interface locally. For installation instructions, command documentation, and CSV format specifications, refer to the CLI documentation.

GitHub CLI README: https://github.com/CredentialEngine/ce-cli/blob/main/README.md

The CLI supports:

• Bulk challenge generation
• Local signing workflows
• Batch DID registration
• CSV-based submission management

A typical workflow is a 3-part process:

1. Login
2. Sign challenges and generate tokens
3. Validate token and publish to IIR

ce login
ce iir bulk-upload-dids sign-challenges --csv input.csv
ce iir bulk-upload-dids publish --output-file Output-input-....csv

The CLI validates:

• CTIDs
• DID formats
• Verification methods
• Signing algorithms

All signing operations occur locally on the issuer’s machine. Private keys are never transmitted to Credential Engine.

Overview for Verifiers

The IIR provides public endpoints for verifier applications to retrieve trusted issuer identity information. The primary verifier workflow is to query the IIR using an issuer DID and receive a Credential Engine-signed JSON Web Token (JWT) containing metadata about the verified issuer. The JWT format is used to provide a cryptographically signed and tamper-evident response that verifiers can independently validate using Credential Engine’s published trust metadata and public signing keys. The verifier decodes and validates the JWT returned by the IIR. Successful validation confirms that the issuer metadata was signed by Credential Engine and has not been altered.

The IIR supports verifier workflows by providing:

• Public trust anchor endpoint
• List of registered issuer DIDs endpoint
• Issuer DID lookup endpoint that returns a Credential Engine-signed JWT

All of these endpoints are open and available to verifier applications via Swagger.

Access Credential Engine’s IIR Swagger: https://issuerregistry.credentialengine.org/swagger/index.html

The IIR does not verify individual credentials, learner achievements, or credential contents. It provides trusted issuer identity metadata that verifiers can use as part of their broader credential verification process.

Verifier Workflow

A typical verifier workflow includes:

1. Extract the issuer DID from a digital credential’s proof.
2. Query the IIR issuer OpenID Federation endpoint using that DID.
3. Receive a Credential Engine-signed JWT from the IIR.
4. Decode the JWT to retrieve issuer metadata.
5. Validate the JWT signature using Credential Engine’s published trust anchor information.
6. Confirm that the issuer DID in the JWT matches the DID referenced in the credential.
7. Review any DID validity period information included in the JWT metadata.
8. Use the returned issuer metadata to support the verifier’s credential trust decision.

OpenID Federation Endpoints

The Issuer Identity Registry (IIR) exposes public OpenID Federation endpoints that allow verifiers, wallets, platforms, and other ecosystem participants to retrieve trusted issuer identity metadata.

Supported endpoints include:

• Trust Anchor’s Entity Configuration endpoint
• Issuer List endpoint
• Issuer DID Fetch endpoint

The Entity Configuration and Issuer DID Fetch endpoints return Credential Engine self-signed JWT responses and federation metadata used during issuer identity verification workflows.

Swagger documentation for the OpenID Federation endpoints is available at: https://issuerregistry.credentialengine.org/swagger/index.html?urls.primaryName=OpenID+Federation

Figure 3: DID submission and OpenID Federation API

Trust Anchor’s Entity Configuration Endpoint

The Entity Configuration endpoint provides the foundational trust metadata for the Issuer Identity Registry (IIR). This endpoint publishes the Credential Engine trust anchor information used by verifiers to validate JWTs returned by the IIR issuer DID endpoint.

The Entity Configuration JWT includes Credential Engine’s:

• DID
• CTID
• Public JWK signing key information
• Governance policy URL

Verifiers use this endpoint to establish trust in the Credential Engine-signed JWTs returned by the IIR.

Endpoint:

GET /oidfed/.well-known/openid-federation

Example request:

curl https://issuerregistry.credentialengine.org/oidfed/.well-known/openid-federation

The trust anchor metadata enables verifiers to:

• Validate JWT signatures returned by the IIR
• Confirm the JWT was issued by Credential Engine
• Retrieve Credential Engine federation metadata
• Reference governance and operational trust information
• Establish trust chain relationships for OpenID Federation workflows

Verifiers should retrieve the Trust Anchor metadata before trusting JWT responses returned by the issuer DID endpoint.

Issuer List Endpoint

The Issuer List endpoint returns the list of issuer DIDs registered in the IIR.

Endpoint:

GET /oidfed/federation_list

Example request:

curl https://issuerregistry.credentialengine.org/oidfed/federation_list

Verifiers may use this endpoint to:

• Discover registered issuer DIDs
• Confirm whether a DID appears in the IIR
• Support trust discovery and caching workflows

OpenID Federation Endpoint

The Issuer DID endpoint returns a Credential Engine-signed JWT containing verified issuer metadata for a specific DID. This endpoint can be queried using a DID or CTID.

Endpoint:

GET /oidfed/federation_fetch?sub={did}

Example request:

curl "https://issuerregistry.credentialengine.org/oidfed/federation_fetch?sub=did:key:z6Mkj8AnYUMWcuNLPZA7dQPpsb5h8YZzzE46osn3C8QjWjyS"

The verifier decodes the returned JWT to access the issuer metadata. The verifier should also validate the JWT signature to confirm that the response was issued by Credential Engine and has not been modified.

JWT Returned by the Issuer DID Endpoint

The JWT returned by the issuer DID endpoint is signed by Credential Engine.

It contains verified issuer metadata including the data shown in the chart below.

It’s used to provide a tamper-evident issuer identity response. If the JWT signature cannot be validated, the verifier should not treat the response as trusted.

Decoding and Validating the JWT

Verifier systems should perform two related actions:

1. Base64 decode the JWT to read the issuer metadata.
2. Validate the JWT signature to confirm the metadata was signed by Credential Engine.

Decoding alone is not sufficient for trust. A verifier must also validate the signature using Credential Engine’s trust anchor metadata.

For manual verification, any user may use https://jwt.io tools to verify signatures of the JWTs returned from the OpenID Federation endpoints using the public JWK present inside it.

Verifier validation should confirm the following:

• JWT was signed by Credential Engine
• JWT has not been altered
• JWT has not expired, if expiration claims are included
• Issuer DID in the response matches the DID requested
• Any DID validity window returned in the metadata is appropriate for the credential being evaluated

Error Handling

If the requested DID is not registered, invalid, unsupported, or cannot be resolved, the endpoint returns an error response rather than a trusted issuer JWT. Verifier systems should handle the following errors.

Relationship to Credential Registry: Consuming Data

The IIR provides verified issuer identity metadata retrieved as a JWT signed by Credential Engine. The Credential Registry provides richer descriptive data about organizations and the credentials they own or offer as CTDL JSON-LD — linked, open data. These registries serve different and complementary purposes.

Figure 4

The CTID returned in the IIR metadata links the verified issuer identity record to the corresponding organization record in the Credential Registry.

Verifiers may use the CTID to retrieve or reference CTDL JSON-LD data stored in the Credential Registry:

• Organization descriptions
• Credentials owned or offered by the organization
• Additional linked data

This separation allows the IIR to remain focused on issuer identity verification while the Credential Registry provides descriptive credential and organization data.

When a CTID is known, get a record from the registry directly by CTID. There are three options:

• Using /envelopes — to return the registry wrapper object that includes metadata about who published the data and links to previous revisions of that data, along with the data itself.

  https://credentialengineregistry.org/envelopes/{CTID}

• Using /graph — to return the full document and any child entities such as blank nodes, or competencies for a competency framework, in a flattened array structure.

  https://credentialengineregistry.org/graph/{CTID}

• Using /resources — to return only the main document and no child documents.

  https://credentialengineregistry.org/resources/{CTID}

An example URI looks like this:

https://credentialengineregistry.org/resources/ce-a4c0a549-aed3-4704-ade2-e81a5d76865b

In most programming languages, an HTTP GET request is straightforward. For example, to get the data and parse it into an object in C#, you could do this:

using System.Text.Json.Nodes;

public JsonObject GetExample()
{
    var jsonText = new HttpClient()
        .GetAsync( "https://credentialengineregistry.org/graph/ce-a4c0a549-aed3-4704-ade2-e81a5d76865b" )
        .Result.Content.ReadAsStringAsync().Result;
    var jsonParsed = (JsonObject) JsonObject.Parse( jsonText );

    return jsonParsed;
}