Integration Guide

Registry API

The registry provides a comprehensive index of all credentials at:

https://registry.siros.org/api/v1/schemas.json

This JSON file contains all TS11-compliant credential schemas, enabling automated configuration of credential ecosystems. See the API Reference for the full specification.

API Response Structure

The registry API follows this structure:

{
  "total": 3,
  "limit": 3,
  "offset": 0,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "version": "1.0.0",
      "attestationLoS": "high",
      "bindingType": "cnf",
      "supportedFormats": ["dc+sd-jwt", "mso_mdoc"],
      "schemaURIs": [
        {
          "formatIdentifier": "dc+sd-jwt",
          "uri": "https://registry.siros.org/example-org/Identity.vctm.json"
        },
        {
          "formatIdentifier": "mso_mdoc",
          "uri": "https://registry.siros.org/example-org/Identity.mdoc.json"
        }
      ],
      "rulebookURI": "https://registry.siros.org/example-org/Identity/rulebook.html",
      "trustedAuthorities": []
    }
  ]
}

Credential Formats

Each credential may include metadata in one or more formats:

Download Script

Use this shell script to download all credential metadata files organized by format:

#!/bin/bash
# Download all credential metadata from SIROS Registry
# Requires: curl, jq

set -e

API_URL="https://registry.siros.org/api/v1/schemas.json"
OUTPUT_DIR="${1:-credentials}"

echo "Fetching registry API..."
REGISTRY=$(curl -s "$API_URL")

# Create output directories
mkdir -p "$OUTPUT_DIR"/{vctm,mdoc,vc}

# Parse schemas and download each format file
echo "$REGISTRY" | jq -c '.data[]' | while read -r schema; do
    ID=$(echo "$schema" | jq -r '.id')

    echo "Processing schema: $ID"

    # Download each schema URI
    echo "$schema" | jq -c '.schemaURIs[]' | while read -r uri_entry; do
        FORMAT=$(echo "$uri_entry" | jq -r '.formatIdentifier')
        URI=$(echo "$uri_entry" | jq -r '.uri')
        FILENAME=$(basename "$URI")

        case "$FORMAT" in
            dc+sd-jwt) DIR="vctm" ;;
            mso_mdoc)  DIR="mdoc" ;;
            jwt_vc_json) DIR="vc" ;;
            *) DIR="other" ; mkdir -p "$OUTPUT_DIR/$DIR" ;;
        esac

        curl -s "$URI" -o "$OUTPUT_DIR/$DIR/$FILENAME"
        echo "  Downloaded: $DIR/$FILENAME"
    done
done

# Generate summary
TOTAL=$(echo "$REGISTRY" | jq '.total')
echo ""
echo "Download complete!"
echo "  Total schemas: $TOTAL"
echo "  Output directory: $OUTPUT_DIR/"

Save this script as download-registry.sh and run:

chmod +x download-registry.sh
./download-registry.sh ./my-credentials

Using with jq

Query the registry directly with jq:

List all schema IDs

curl -s https://registry.siros.org/api/v1/schemas.json | \
  jq -r '.data[].id'

Get all supported formats

curl -s https://registry.siros.org/api/v1/schemas.json | \
  jq -r '.data[] | "\(.id): \(.supportedFormats | join(", "))"'

Find high-assurance credentials

curl -s https://registry.siros.org/api/v1/schemas.json | \
  jq '.data[] | select(.attestationLoS == "high")'

List all SD-JWT VC URIs

curl -s https://registry.siros.org/api/v1/schemas.json | \
  jq -r '.data[].schemaURIs[] | select(.formatIdentifier == "dc+sd-jwt") | .uri'

Programmatic Access

The registry API can be fetched programmatically from any language:

JavaScript/Node.js

const response = await fetch(
  'https://registry.siros.org/api/v1/schemas.json'
);
const registry = await response.json();

// Iterate schemas
for (const schema of registry.data) {
  console.log(`${schema.id}: ${schema.attestationLoS}`);

  // Download SD-JWT VC type metadata
  const vctmURI = schema.schemaURIs
    .find(u => u.formatIdentifier === 'dc+sd-jwt');
  if (vctmURI) {
    const vctm = await fetch(vctmURI.uri).then(r => r.json());
    // Use credential type metadata...
  }
}

Python

import requests

registry = requests.get(
    'https://registry.siros.org/api/v1/schemas.json'
).json()

# Iterate schemas
for schema in registry['data']:
    print(f"{schema['id']}: {schema['attestationLoS']}")

    # Download SD-JWT VC type metadata
    for uri_entry in schema['schemaURIs']:
        if uri_entry['formatIdentifier'] == 'dc+sd-jwt':
            vctm = requests.get(uri_entry['uri']).json()
            # Use credential type metadata...

Go

resp, _ := http.Get(
    "https://registry.siros.org/api/v1/schemas.json",
)
defer resp.Body.Close()

var registry struct {
    Data []struct {
        ID             string `json:"id"`
        AttestationLoS string `json:"attestationLoS"`
        SchemaURIs     []struct {
            FormatIdentifier string `json:"formatIdentifier"`
            URI              string `json:"uri"`
        } `json:"schemaURIs"`
    } `json:"data"`
}
json.NewDecoder(resp.Body).Decode(&registry)

for _, s := range registry.Data {
    fmt.Printf("%s: %s\n", s.ID, s.AttestationLoS)
}

Use Cases

• Issuer Configuration — Automatically configure credential issuance endpoints with display metadata and claim definitions
• Verifier Setup — Pre-populate verifier applications with known credential types and their validation schemas
• Wallet Integration — Enable wallets to discover and properly render credentials from multiple issuers
• CI/CD Pipelines — Fetch latest credential definitions during deployment to keep systems synchronized
• Monitoring — Track changes to credential definitions across the ecosystem

Caching Considerations

The registry is rebuilt periodically. When integrating:

• Cache responses locally to reduce API calls
• Consider polling at reasonable intervals (e.g., hourly or daily)
• The registry is served via GitHub Pages CDN with standard caching headers
• All API responses are JWS-signed — verify using the published JWKS

Related Documentation

• TS11 Compliance — How this registry implements TS11
• API Reference — Full API documentation
• Publish Your Credentials — Add your credentials to the registry
• GitHub Action Setup — Automate credential metadata generation
• Markdown Format — Define credentials in Markdown
• Support — Get help and report issues