Skip to main content

​
Overview

The EBSI (European Blockchain Services Infrastructure) Trusted Issuers Registry (TIR) is a standardized API for managing and querying trusted credential issuers. VCVerifier provides full support for EBSI-compliant TIR implementations.

​
How EBSI TIR Works

The EBSI TIR maintains a registry of authorized credential issuers, including:
  • Issuer DIDs - Decentralized identifiers for each trusted issuer
  • Attributes - Metadata about the issuer’s capabilities and authorizations
  • Credential Types - Types of credentials the issuer is authorized to issue
  • Claims - Specific claims the issuer can make in credentials
  • Validity Periods - Time ranges during which the issuer’s authorization is valid

​
Configuration

​
Basic Configuration

Configure EBSI TIR verification for specific credential types: 
configRepo:
  services:
    testService:
      scope:
        - VerifiableCredential
        - CustomerCredential
      trustedParticipants:
        VerifiableCredential:
          - type: ebsi
            url: https://tir-pdc.ebsi.fiware.dev
        CustomerCredential:
          - type: ebsi
            url: https://tir-pdc.ebsi.fiware.dev
For backward compatibility, EBSI TIR is the default registry type. If no type is specified, VCVerifier assumes type: ebsi.

​
Advanced Configuration with Trusted Issuers Lists

You can also configure trusted issuers lists alongside trusted participants: 
configRepo:
  services:
    testService:
      oidcScopes:
        default:
          credentials:
            - type: CustomerCredential
              # Trusted participants endpoint
              trustedParticipantsLists:
                VerifiableCredential:
                  - https://tir-pdc.ebsi.fiware.dev
                CustomerCredential:
                  - https://tir-pdc.ebsi.fiware.dev
              # Trusted issuers endpoint
              trustedIssuersLists:
                VerifiableCredential:
                  - https://tir-pdc.ebsi.fiware.dev
                CustomerCredential:
                  - https://tir-pdc.ebsi.fiware.dev

​
API Versions

VCVerifier supports both EBSI TIR API versions with automatic fallback:
  • v4 API - /v4/issuers/{did} (tried first)
  • v3 API - /v3/issuers/{did} (fallback if v4 fails)
The client automatically detects which version is supported by the registry and adapts accordingly. 
GET {tirEndpoint}/v4/issuers/{did}

​
Response Format

When querying an EBSI TIR, the registry returns trusted issuer information: 
{
  "did": "did:key:z6MkigCEnopwujz8Ten2dzq91nvMjqbKQYcifuZhqBsEkH7g",
  "attributes": [
    {
      "hash": "0x123...",
      "body": "encoded-attribute-data",
      "issuerType": "TrustedIssuer",
      "tao": "TrustAnchorOperator",
      "rootTao": "RootTrustAnchor"
    }
  ]
}

​
Issuer Attributes

Each trusted issuer entry includes attributes that define:
  • Credentials Type - Which credential types the issuer can issue
  • Valid Time Ranges - When the issuer’s authorization is active
  • Allowed Claims - Specific claims the issuer can make
  • Claim Values - Permissible values for specific claims

​
Verification Flow

1

Credential Received

VCVerifier receives a Verifiable Credential from a wallet
2

Extract Issuer DID

The issuer’s DID is extracted from the credential
3

Check Cache

VCVerifier checks if the issuer verification result is cached
4

Query TIR (if not cached)

If not cached, VCVerifier queries the configured TIR endpoint:
  • Tries v4 API first: GET /v4/issuers/{did}
  • Falls back to v3 API if needed: GET /v3/issuers/{did}
5

Evaluate Response

  • HTTP 200: Issuer is trusted, verification succeeds
  • HTTP 404: Issuer not found, verification fails
  • Other codes: Error condition, verification fails
6

Cache Result

The verification result is cached to optimize future requests

​
Authentication

EBSI TIR endpoints may require authentication using OAuth2 machine-to-machine flows: 
verifier:
  # M2M configuration for TIR authentication
  m2m:
    authEnabled: true
    clientId: "your-client-id"
    clientSecret: "your-client-secret"
    tokenEndpoint: "https://auth.ebsi.eu/token"
  # Cache configuration
  tirCacheExpiry: 3600  # seconds
  tilCacheExpiry: 3600  # seconds
When authEnabled: true, VCVerifier automatically refreshes authentication tokens every 30 seconds to ensure uninterrupted access to protected TIR endpoints.

​
Performance Optimization

VCVerifier implements several optimizations for EBSI TIR queries:

​
Caching Strategy

  • Issuer Cache: Caches full issuer responses to avoid repeated queries
  • Existence Cache: Caches simple yes/no trust checks (HTTP 200 vs 404)
  • Configurable Expiry: Adjust cache duration via tirCacheExpiry setting

​
HTTP Client Configuration

// Keep-alives disabled to avoid race condition EOFs
transport := http.DefaultTransport.(*http.Transport).Clone()
transport.DisableKeepAlives = true
httpClient := &http.Client{Transport: transport}
Keep-alive connections are intentionally disabled to prevent race condition errors. Since most responses are served from cache, this has minimal performance impact.

​
Testing Your Configuration

Verify your EBSI TIR configuration is working: 
# Check if a specific issuer is trusted
curl -X GET "https://tir-pdc.ebsi.fiware.dev/v4/issuers/did:key:z6MkigCEnopwujz8Ten2dzq91nvMjqbKQYcifuZhqBsEkH7g"

# Expected response for trusted issuer: HTTP 200
# Expected response for unknown issuer: HTTP 404

​
Common Use Cases

Use one EBSI TIR instance for all credential types in your system:
trustedParticipants:
  VerifiableCredential:
    - type: ebsi
      url: https://tir-pdc.ebsi.fiware.dev
  CustomerCredential:
    - type: ebsi
      url: https://tir-pdc.ebsi.fiware.dev
  EmployeeCredential:
    - type: ebsi
      url: https://tir-pdc.ebsi.fiware.dev
Use specialized TIR instances for different credential categories:
trustedParticipants:
  EducationCredential:
    - type: ebsi
      url: https://education-tir.ebsi.eu
  IdentityCredential:
    - type: ebsi
      url: https://identity-tir.ebsi.eu
Use different TIR endpoints for different environments:
# Development
trustedParticipants:
  VerifiableCredential:
    - type: ebsi
      url: https://tir-pdc.ebsi.fiware.dev

# Production
trustedParticipants:
  VerifiableCredential:
    - type: ebsi
      url: https://tir.ebsi.eu

​
Next Steps

Gaia-X Registry

Learn about Gaia-X Registry integration

Mixed Usage

Combine EBSI TIR with other registries

Build docs developers (and LLMs) love

Get started for freeTalk to us