Liccium Developer Portal
Getting Started

General Information

The Liccium API facilitates the declaration of metadata and rights using cryptographic methods. This section provides an overview of key processes required for making API calls.

Overview

Liccium uses a combination of cryptographic signatures and structured metadata to ensure the integrity and authenticity of content declarations. Understanding these fundamental concepts is essential for successful API integration.

Key Concepts

Cryptographic Validation

All declarations in Liccium use cryptographic signatures to ensure:

  • Authenticity: Proof that the declaration comes from the claimed source
  • Integrity: Assurance that the data hasn't been tampered with
  • Non-repudiation: The ability to prove that a declaration was made by a specific entity

Decentralized Identifiers (DIDs)

Liccium uses Decentralized Identifiers to associate cryptographic keys with domain ownership or key-based identity, enabling trustless verification of declarations.

Metadata Collection

To make a proper API call, a structured metadata object must be included in the HTTP request body.

Metadata Structure

The metadata object contains essential information required for a declaration, including:

  • Cryptographic Signatures: For validation, namely signature and tsaSignature (and optionally optOutRegistrySignature and optOutRegistryTsaSignature when publishing to the opt-out registry)
  • Public Metadata: The publicMetadata section stores core declaration data including iscc, declarerId, credentials, and optional plugin metadata (e.g. TDMAI, IPTC)
  • Declaration Metadata: The declarationMetadata section wraps publicMetadata and optional registry-specific payloads

Example Metadata Object

JSONCode
 
{
  "signature": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImp3ayI6e319.payload.signature",
  "tsaSignature": {
    "tsr": "base64-encoded-timestamp-response",
    "tsq": "base64-encoded-timestamp-request"
  },
  "declarationMetadata": {
    "publicMetadata": {
      "$schema": "https://w3id.org/liccium/schema/0.1.0.json",
      "iscc": "ISCC:KEC2EHPLVKPVDFVORULRVCUFXL3DZ4SA6JSDQLNOXEVYYCXR4N5IBDY",
      "name": "Example Content",
      "description": "Sample content description",
      "mediatype": "image/jpeg",
      "timestamp": 1736251200000,
      "declarerId": "did:web:example.com",
      "credentials": [
        {
          "@context": ["https://www.w3.org/ns/credentials/v2"],
          "type": ["VerifiableCredential", "VerifiableSupplier"],
          "proof": {
            "type": "JwtProof2020",
            "jwt": "eyJhbGciOiJFUzI1NiJ9..."
          }
        }
      ]
    }
  }
}

Required Fields: All metadata objects must include cryptographic signatures (signature, tsaSignature) for successful validation. When including optional registry payloads (e.g. opt-out registry), provide the corresponding registry signature and TSA signature (optOutRegistrySignature, optOutRegistryTsaSignature).

Metadata Validation Process

  1. Structure Validation

    The API validates that all required fields are present and properly formatted.

  2. Signature Verification

    The cryptographic signature is verified against the declared identity using the associated cryptographic keypair.

  3. Timestamp Validation

    The TSA signature is validated to ensure the declaration was made at the claimed time.

Best Practices

Security Considerations

  • Never include sensitive information in publicMetadata
  • Ensure your private keys are securely stored and never transmitted
  • Validate all metadata before signing

Next Steps

Now that you understand the basics of metadata collection, you can proceed to:

Last modified on
OverviewRequirements