Docs Using the wallet Credentials

Credential Management

Understanding Verifiable Credentials

What is a Verifiable Credential?

A Verifiable Credential is a digital document that:

  • Makes a claim: States something about a subject (e.g., “Company X is licensed to operate”)
  • Is issued by you: Signed with your organization’s DID and keys
  • Can be verified: Anyone can cryptographically prove it’s authentic
  • Cannot be forged: The signature prevents tampering

Real-world examples: - Business licenses - Membership certificates - Product certifications - Authorization letters - Compliance attestations

Credential Structure

Every credential has:

  1. Issuer: Your organization’s DID (who issued it)
  2. Subject: The DID or entity the credential is about (the id in credential subject)
  3. Claims: The actual information in credential subject being certified
  4. Signature: Cryptographic proof of authenticity
  5. Issuance Date: When it was created
  6. Expiration Date: When it expires (optional)
  7. Status: Whether it’s active, revoked, or suspended

Issuing Your First Credential

Understanding Credential Templates

The GS1 ready EUBW Company Wallet uses credential templates to streamline credential issuance. Templates define:

  • The credential type and structure
  • Required and optional fields
  • Property data types and validation rules
  • JSON-LD contexts for semantic definitions

Why templates?

  • Ensures consistency across similar credentials
  • Reduces errors by providing structured forms
  • Enables field validation and type checking
  • Simplifies repeated issuance of the same credential type

Two Ways to Issue Credentials

Option 1: Using Credential Templates (UI)

This is the standard method for issuing credentials through the web interface. You must first create or select a credential template, then fill in the template fields.

Requirements:

  1. At least one credential template created
  2. A DID with assertion keys
  3. The necessary permissions

Option 2: Using the Issuance API (Advanced)

For programmatic or custom credential issuance, you can use the REST API endpoint /api/credentials/issue directly. This bypasses templates and accepts a complete credential JSON structure.

Use cases:

  • Batch credential issuance
  • Integration with external systems
  • Custom credential types not covered by templates

See the API documentation (OpenAPI/Swagger) for details on the /api/credentials/issue endpoint.

Creating Your First Template

Before issuing credentials, you need to create a template:

  1. Click Credential Templates in the main menu
  2. Click Create template

Step 1: Add JSON-LD Contexts

Templates are built from JSON-LD contexts that define credential schemas:

  1. Enter a context URL (e.g., https://schema.org or a custom schema)
  2. Click the download icon to load the context
  3. Add additional contexts if needed
  4. The standard W3C credentials context is included automatically

Example contexts:

  • https://schema.org - General purpose schema
  • https://gs1.org/voc/ - GS1 vocabulary (if GS1 plugin enabled, see GS1 Digital License)
  • Custom organization schemas

Step 2: Configure Template Basics

  1. Template Name: Give it a descriptive name (e.g., “Business License”)
  2. Credential Type: The credential type URI from your context
  3. Description: Optional description of the template’s purpose
  4. Issuer DID: Select which DID will issue credentials from this template

Step 3: Select Properties

After loading contexts, available properties from those contexts appear:

  1. Browse available properties from the loaded vocabularies
  2. Select properties to include in your template
  3. Configure each property:
    • Mark as required or optional
    • Set default values
    • Add descriptions/hints for users
    • Configure validation rules
    • Set property positioning/ordering

Step 4: Configure Template Settings

  • Valid From: Default issuance date (usually current date)
  • Valid Until: Optional default expiration date
  • Enable Revocation: Allow credentials to be revoked
  • Enable Suspension: Allow credentials to be suspended

Step 5: Save Template

  1. Review all template settings
  2. Click Save Template
  3. Template is now available for credential issuance

Issuing a Credential from a Template

Once you have templates created:

Step 1: Access Credential Issuance

  1. Click Credentials in the navigation menu
  2. Click Issue Credential button (+ icon)

Note: If you don’t see the Issue Credential button, you don’t have the CREATE_CREDENTIAL permission.

Step 2: Select Template

  1. From the Template Selection dropdown, choose your template
  2. The form will populate with fields defined by the template
  3. Required fields are marked with *

Step 3: Enter Credential Subject

Subject Identifier: Enter the identifier for who/what this credential is about

Format: Must be a valid URI/IRI

Examples:

  • Another organization’s DID: did:web:partner.com
  • A product: https://example.com/products/12345
  • An identifier: urn:epc:id:sgtin:0614141.112345.400

Step 4: Fill Template Fields

Complete all fields defined by your template:

  1. Required fields must be filled (marked with *)
  2. Optional fields can be left empty
  3. Field types determine input format:
    • Text fields for strings
    • Date pickers for dates
    • Number fields for numeric values
    • Checkboxes for boolean values
    • Dropdowns for enumerated values

Example: Business License Template

Subject Identifier: did:web:partner.com
Company Name: Acme Corporation
License Number: BL-2026-001234
Authorized For: Food Manufacturing
Jurisdiction: European Union
Valid From: 2026-01-27
Valid Until: 2027-01-27

Step 5: Configure Credential Settings

  • Valid Until: Adjust expiration date if different from template default
  • Enable Revocation: Toggle if you want to override template setting
  • Enable Suspension: Toggle if you want to override template setting
  • Visibility: Choose Public (appears in registry) or Private

Step 6: Select Signing Key

  1. From the Issuer and Key section, select a key
  2. Only assertion keys from the template’s issuer DID appear
  3. The key you choose signs the credential
  4. Signature Format: Select Data Integrity (recommended) or JWT-VC

Step 7: Provide User Secret

  1. Upload your User Secret key file for the selected key (if configured)
  2. This provides the additional encryption layer to access the key
  3. If the key uses service-secret-only mode, this step is automatic

For multi-controller keys:

  • All controllers must provide their secrets
  • You’ll see a pending signing request
  • Credential is issued when all controllers approve

Step 8: Review and Issue

  1. Review all credential details in the summary
  2. Click Issue Credential button
  3. Credential is created and signed
  4. You’ll be redirected to the credential details page

Step 9: Credential Delivery

After issuance, you can:

  1. View the credential in JSON format
  2. Download as a JSON file
  3. Copy to clipboard
  4. Share the public registry URL (if public visibility)
  5. Revoke or Suspend if needed (if enabled)

Managing Issued Credentials

Viewing Credentials

The Credentials list shows:

  • Credential ID: Unique identifier
  • Subject: Who/what the credential is about
  • Type: Credential type(s)
  • Status: Active, Revoked, or Suspended
  • Issued Date: When it was created
  • Expiration: When it expires (if set)
  • Action buttons: View, revoke, delete

Searching Credentials

Use the search filters:

Search by: - Credential ID: Exact or partial ID - Subject ID: Find credentials about a specific subject - Issuer DID: Filter by which DID issued them - Status: Show only active, revoked, or suspended

Searching steps:

  1. Enter search terms in filter fields
  2. Results update automatically
  3. Clear filters to show all credentials

Credential Details

Click on a credential to view:

  • Full credential JSON: Complete credential data
  • Signature details: How it was signed
  • Status information: Current status and history
  • Verification link: URL to verify the credential
  • Action buttons: Revoke, suspend, download

Downloading Credentials

Download options:

  1. JSON: Raw credential data
  2. JWT: JWT-encoded version (if available)
  3. QR Code: Scannable code containing credential

Steps:

  1. Open credential details
  2. Click Download button
  3. Choose format
  4. File downloads to your computer

Sharing Credentials

Public credentials can be shared via:

  1. Public Registry URL: Direct link to verify
  2. Credential JSON: Send the file
  3. QR Code: For mobile scanning

Private credentials must be:

  • Downloaded and sent securely
  • Shared only with authorized parties
  • Not published to public registry

Credential Status Management

Revoking Credentials

When to revoke:

  • Credential information is no longer accurate
  • Subject is no longer authorized
  • Credential was issued in error
  • Security compromise occurred

Revocation steps:

  1. Find the credential in Generic Credentials
  2. Open its actions menu and choose Revoke
  3. Optionally enter a Reason for revocation
  4. Confirm the revocation
  5. Status updates to Revoked

Effect:

  • Credential verification fails immediately
  • Status list is updated
  • Holders are notified (if implemented)

Suspending Credentials

When to suspend:

  • Temporary issues need investigation
  • Pending renewal or update
  • Compliance check in progress

Suspension is temporary and can be reversed.

Suspension steps:

  1. Find the credential in Generic Credentials
  2. Open its actions menu and choose Suspend
  3. Enter a Reason for suspension
  4. Confirm the suspension
  5. Status updates to Suspended

Effect:

  • Credential verification fails temporarily
  • Can be reinstated later
  • Suitable for temporary issues

Reinstating Suspended Credentials

To reactivate a suspended credential:

  1. Find the suspended credential
  2. Open its actions menu and choose Reactivate
  3. Confirm
  4. Status returns to Active

Advanced Credential Features

Multi-Controller Signing

For credentials that need more than one person:

  1. Use a key with controller groups (see Key Management)
  2. After you sign, the request stays pending until the key’s rule is met
  3. One person from each group provides a secret
  4. People in the same group are alternatives: any one of them is enough for that group

Viewing pending signatures:

  1. Open the bell in the header, or the requests on the dashboard
  2. Each person who still needs to act sees the request
  3. Upload your key file if this key uses one

Managing Multiple Templates

For organizations issuing different types of credentials:

  1. Create multiple templates for different credential types
  2. Name them clearly (e.g., “Business License”, “Membership Certificate”, “Product Certification”)
  3. Document each template’s purpose in the description field
  4. Review and update templates periodically

Batch Issuance via API

For issuing many similar credentials programmatically:

  1. Create a template in the UI to standardize the credential structure
  2. Use the API endpoint /api/credentials/issue for automated issuance
  3. Prepare your data as JSON following the template structure
  4. Issue credentials programmatically with consistent format

Example use cases:

  • Issuing certificates to multiple course participants
  • Creating product credentials for inventory items
  • Generating membership credentials for new members

See the API documentation for details on the /api/credentials/issue endpoint and the SigningRequest structure.

Public vs Private Credentials

Public credentials:

  • Published to the public registry
  • Anyone can resolve and verify
  • Good for certifications, licenses

Private credentials:

  • Not in public registry
  • Shared directly with recipients
  • Good for confidential information

Making credentials public:

  1. Open the credential
  2. Open the actions menu and choose Change visibility
  3. In Update Credential Visibility, select Public

Verifying Credentials

Verifying Your Own Credentials

To check a credential you issued:

  1. Open the credential details
  2. Click Verify button
  3. Verification report shows:
    • Signature validity
    • Issuer DID resolution
    • Status check (not revoked/suspended)
    • Expiration check

Sharing for External Verification

Provide recipients with:

  1. Credential JSON: they can verify it with any verifier
  2. The credential id: that id is the public address. Copy it with Copy ID

When the company has no registry base URL, a credential issued without its own id looks like:

https://your-wallet.com/api/registry/vc/{uuid}

Recipients can open that address in a browser, which goes to the verifier, or paste it into a verifier that fetches JSON-LD or a VC-JWT. Other address patterns are in Registry addresses.

Credential Best Practices

Issuance Best Practices

  • Use descriptive types: Make credential purpose clear
  • Set expiration dates: For time-sensitive credentials
  • Enable revocation: Always allow future revocation
  • Include sufficient claims: Provide all necessary information
  • Use standard contexts: Follow industry schemas when available
  • Sign with stable keys: Use keys you’ll maintain long-term
  • Document your process: Keep records of what you issue

Management Best Practices

  • Regular audits: Review issued credentials periodically
  • Revoke promptly: When credentials become invalid
  • Use suspension cautiously: Only for temporary issues
  • Monitor expiration: Renew before expiration
  • Track revocations: Document why credentials were revoked
  • Backup credentials: Keep copies of issued credentials

Security Best Practices

  • Verify recipients: Ensure subject IDs are correct
  • Protect signing keys: Use multi-controller for important credentials
  • Audit credential issuance: Review who issues what
  • Limit permissions: Not everyone needs issuance rights
  • Monitor suspicious activity: Check audit logs regularly