Overview

Document sections

SSI runtimes

Introduction

Role-based SSI guide. Walk through the three roles, understand data boundaries, and compare examples across web, server, and mobile SDK runtimes.

Self-sovereign identity becomes easier to understand when each responsibility has a clear owner. An Issuer creates a Verifiable Credential, the Holder keeps it in a mobile secure vault, and a Verifier requests and verifies a Verifiable Presentation (VP).

Important note

[Issuer validates and signs VC] -> [Holder stores VC on mobile] -> [Holder consents and creates VP] -> [Verifier validates VP]

Key concepts

Issuer

Validates source data, signs the credential, and sends a credential offer through DIDComm.

Holder

Keeps the credential in one mobile secure vault and decides when to disclose claims.

Verifier

Requests only the claims it needs and validates signatures, challenge, and credential status.

DID registry

Publishes and resolves DID Documents through CertNet, did:web, ION, or an internal registry.

Credential issuance

Issuer

STEP 01 of 03 in the role-based SSI flow.

Who creates a credential and where does the code run?

The issuer checks data, signs a VC, and sends it to the user. It may integrate on internal web, server, or app.

Data and key boundary

Organization signing keys must be protected for the runtime, preferably by an HSM on server.

Reference

Runtime	SDK example	When to use
Web client	@identra/web with Browser JavaScript or TypeScript	Internal issuer tools with a controlled key policy
Server	@identra/node or identra-go	Protected signing services backed by HSM or managed KMS
Mobile app	@identra/react-native, Android SDK, or iOS SDK	Managed internal issuer applications

Flow steps

Initialize: Initialize the SDK for the current runtime.
Create DID: Create or load the issuer DID on the selected DID registry.
Sign VC: Sign a Verifiable Credential for the recipient DID.
Send offer: Send the credential offer over DIDComm.

Code example

1. Choose runtime

2. Choose SDK and language

Browser · JavaScript · @identra/web

import { Identra } from '@identra/web';

// Illustrative SDK, not for production use.
const identra = new Identra({
  environment: 'sandbox',
  didRegistry: {
    defaultProvider: 'certnet',
    providers: ['certnet', 'did:web', 'ion', 'internal-ledger']
  },
  mediatorUrl: 'https://mediator.sandbox.identra.dev'
});

// Runs for the issuer on web, server, or an internal app.
const issuer = await identra.issuer.create({
  did: 'did:identra:university',
  keyProtection: 'platform-secure-storage'
});

// A DID Document can be published to multiple registries; CertNet is only the default sandbox provider.
await issuer.publishDidDocument({
  registries: ['certnet', 'did:web']
});

const credential = await issuer.issue({
  // The Holder DID is obtained after connection setup or from the business system.
  subjectDid: 'did:identra:holder',
  type: 'UniversityDegree',
  claims: { degree: 'Information Technology', graduationYear: 2026 }
});

// The credential is not placed in the QR; the QR only bootstraps the DIDComm connection.
await issuer.didcomm.sendCredentialOffer({ credential, connectionId });

Details

The Holder DID is obtained after connection setup or from the business system. The credential is not placed in the QR; the QR only bootstraps the DIDComm connection.

Credential holding and sharing

Code example

1. Choose runtime

This flow supports mobile only because credentials must remain in one secure vault on the phone.

2. Choose SDK and language

React Native · TypeScript · @identra/react-native

import { IdentraMobile } from '@identra/react-native';

// Illustrative SDK, not for production use.
const identra = new IdentraMobile({
  environment: 'sandbox',
  didRegistry: {
    defaultProvider: 'certnet',
    providers: ['certnet', 'did:web', 'ion', 'internal-ledger']
  },
  mediatorUrl: 'https://mediator.sandbox.identra.dev'
});

// Runs only on the phone. VCs cannot be exported to web or a second device.
const wallet = await identra.holder.activateSingleDeviceVault({
  migrationPolicy: 'wipe-old-device',
  exportCredentials: false,
  requireBiometric: true
});

await wallet.didcomm.onCredential(async (credential) => {
  // The SDK resolves the DID Document from the matching registry provider.
  await wallet.verifyAndStore(credential);
});

const request = await wallet.scanPresentationQr(scannedQr);
const consent = await wallet.requestUserConsent(request);
const presentation = await wallet.createPresentation({ request, consent });
await wallet.didcomm.sendPresentation(presentation);

Credential verification

Verifier

STEP 03 of 03 in the role-based SSI flow.

How does the verifier trust a VP?

The verifier receives a VP, extracts holder and issuer DIDs, resolves DID Documents through the matching registry provider such as CertNet, did:web, or ION, then checks signatures, challenge, and revocation status.

Data and storage boundary

A verifier may run on web, server, or app, but it must not store VCs as a Holder.

Guidance

Create request: Create a presentation request with a replay-resistant challenge.
Show QR: Display a QR containing the DIDComm invitation.
Receive VP: Receive the VP over the newly established connection.
Resolve and verify: Resolve holder and issuer DIDs through the registry provider and verify.

Code example

1. Choose runtime

2. Choose SDK and language

Browser · JavaScript · @identra/web

import { Identra } from '@identra/web';

// Illustrative SDK, not for production use.
const identra = new Identra({
  environment: 'sandbox',
  didRegistry: {
    defaultProvider: 'certnet',
    providers: ['certnet', 'did:web', 'ion', 'internal-ledger']
  },
  mediatorUrl: 'https://mediator.sandbox.identra.dev'
});

// Runs for the verifier on web, server, or an app.
const verifier = await identra.verifier.create({
  did: 'did:identra:jobs-example'
});

const request = await verifier.createPresentationRequest({
  credentialType: 'UniversityDegree',
  // Request only the required claims to reduce holder disclosure.
  fields: ['degree', 'graduationYear'],
  challenge: crypto.randomUUID()
});
const qrDataUrl = await verifier.createQr(request);

const presentation = await verifier.didcomm.waitForPresentation(request.id);
const result = await verifier.verify({
  presentation,
  // The SDK resolves the DID Document from the matching registry provider.
  resolveDid: (did) => identra.didRegistry.resolveDidDocument(did),
  checkCredentialStatus: true
});

if (result.verified) grantAccess();

Was this page helpful?

Let us know what you think to help us improve.

Status	Meaning	Recommended action
created	Session exists but has not started	Present the flow before the token expires
pending	The user is completing required steps	Wait; do not create another Inquiry
submitted	Evidence has been sent for evaluation	Show a processing state
completed	A final decision is available	Fetch checks and apply your policy
needs_review	Automated checks require human review	Restrict the action until review finishes
expired	The session token is no longer valid	Create a new Inquiry if verification is still needed

Field	Required	Guidance
reference_id	Yes	Unique internal event or order ID
type	Yes	Stable snake_case business event name
occurred_at	Yes	UTC timestamp when the event occurred
amount / currency	For money movement	Integer minor units and ISO 4217 currency
account_id	Recommended	Opaque internal account reference
signals	Recommended	Device, network, location, and session context

Recommendation	Typical meaning	Suggested handling
allow	No material risk detected	Continue and record the decision
challenge	Additional assurance is useful	Request step-up verification
review	Signals conflict or exceed a threshold	Queue for an authorized analyst
block	Strong policy or fraud match	Stop the action and protect the account

Lifecycle	States and records
Module	Draft, testing, published, deprecated, archived
Credential	Active, suspended, revoked, expired
History	Issuance time, module version, delivery method, status changes
Audit	Actor, action, reason, environment, timestamp

Type	Examples	Action
Additive	New optional field or endpoint	No immediate action; update schemas when useful
Behavioral	Improved risk model or retry timing	Review metrics and documented expectations
Deprecation	Older header or SDK method scheduled for removal	Migrate before the published end date
Breaking	Required field or changed response contract	Adopt through a new pinned API version

Feature	Replacement	End of support
X-Identra-Signature	Identra-Signature with Identra-Timestamp	2026-11-30
page[offset]	Cursor pagination with page[after]	2027-02-28
SDK complete callback payload v1	Fetch the Inquiry by ID	2027-04-30

Overview

SSI runtimes

Introduction

Important note

Key concepts

Issuer

Holder

Verifier

DID registry

Credential boundaries

Introduction

Most important rule

DID registry is not locked to CertNet

Important note

Credential issuance

Issuer

Who creates a credential and where does the code run?

Data and key boundary

Reference

Flow steps

Code example

Details

Credential holding and sharing

Holder

Where does the credential live and how is it shared?

Data and device boundary

Guidance

Code example

Credential verification

Verifier

How does the verifier trust a VP?

Data and storage boundary

Guidance

Code example

Was this page helpful?

Inquiries

Inquiry concepts

Introduction

Key concepts

Template

Reference ID

Session token

Decision

Important note

Create an Inquiry

Introduction

Code example

Details

Code example 2

Inquiry lifecycle

Introduction

Reference

Handle results safely

Introduction

Guidance

Production checklist

Guidance

Was this page helpful?

Transactions

Transaction monitoring overview

Introduction

Key concepts

Payments

Account events

Marketplace activity

Custom events

Design the event schema

Introduction

Reference

Important note

Send a Transaction

Introduction

Code example

Details

Interpret recommendations

Reference

Introduction

Operational guidance

Guidance

Was this page helpful?