Login
Why LogiHashScannerAdES VerifierAPIAPI demoDocumentationTry LogiHash

LogiHash Documentation

Form and API reference

This page documents the current behavior of the Try platform form and API demo: all supported fields, allowed values, required rules, and practical constraints for production-ready T-Code generation.

Important creator rule

Creator identity data is account-level and must stay consistent. It is not meant to change for every T-Code. Per-item differences should go into object type, custom fields, validity date, and optional linked document metadata.

T-Code form fields (GUI Interface)

Creator NameRequired

Allowed: Non-empty text

Notes: Creator identity for the issuing entity.

Address (Street, House Number, Postal Code, City, Country)Required

Allowed: All non-empty text values

Notes: All five address fields are mandatory.

Object TypeRequired

Allowed: Preset: ID Card, Contract, Invoice, Certificate, Diploma, Permit, Badge, Ticket, Voucher, Warranty, Membership, or custom text

Notes: Custom mode is available via "Other".

T-Code LabelOptional

Allowed: Optional text

Notes: Creator-side helper label, intentionally not encrypted.

Valid UntilRequired

Allowed: YYYY-MM-DD date, minimum today

Default: One year from today (GUI initial date)

Notes: Must be on or after today.

LogoOptional

Allowed: Image upload (base64 data URL), max 2 MB

Notes: Optional branding logo.

Linked DocumentOptional

Allowed: Accepted types: pdf, doc/docx, xml, xls/xlsx, ppt/pptx, images

Notes: Supports optional label and optional EN/DE/FR label translations.

Additional Custom FieldsRequired

Allowed: At least 4 entries, each with non-empty label and value

Notes: Extra rows allowed; translation toggle supports EN/DE/FR per row.

Download FormatRequired

Allowed: PNG | JPG | WebP | SVG

Default: PNG (GUI); png (API example)

Notes: Equivalent to API field output_image_format.

T-Code display options in GUI interface

The GUI supports the same visual controls reflected in display_options for API usage. Use this section to keep rendered T-Codes visually consistent across channels.

T-Code colorRequired

Allowed: black, logihash blue, navy, darkGreen, maroon, purple, darkGray, brown

Default: black (maps to #000000 in API)

Notes: These map to fixed hex values used by the API and GUI validator.

T-Code backgroundRequired

Allowed: transparent | white

Default: transparent

Notes: Transparent is ideal for overlay usage; white is print-friendly on noisy backgrounds.

Scan text enabledRequired

Allowed: true | false

Default: true

Notes: Toggles the sentence shown above or below the code.

Scan text contentRequired

Allowed: Default sentence or custom sentence

Default: “Scan to verify with the LogiHash App” (when not using custom text)

Notes: Custom mode uses your own sentence instead of the default.

Scan text positionRequired

Allowed: above | below

Default: below

Notes: Controls where the sentence appears relative to the T-Code.

Scan text alignmentRequired

Allowed: left | center | right

Default: center

Notes: Text alignment inside the generated image block.

Scan text colorRequired

Allowed: Same palette as T-Code color

Default: black

Notes: GUI and API both enforce the same allowed color set.

App buttonsRequired

Allowed: enabled true|false, style filled|outlined, color from palette

Default: enabled false; when enabled: style filled, color black

Notes: Adds in-image app-action buttons for branded visual style.

Generate API request

API base endpoint: https://api.logihash.com

Generate path: /api/v1/tcode/generate — Verify/Retrieve path: /api/v1/tcode/verify-retrieve

creator_nameRequiredstring

Allowed: Non-empty

Notes: Core creator identity.

tcode_labelOptionalstring

Allowed: Any string

Notes: Optional creator-side label.

addressRequiredobject

Allowed: Must include all address subfields as non-empty strings

Notes: street, house_number, postal_code, city, country are required.

object_typeRequiredstring

Allowed: Non-empty

Notes: Usually matches one of form object types.

valid_untilRequiredstring

Allowed: YYYY-MM-DD

Default: One year from creation date

Notes: Expiration date for positive verification.

output_image_formatRequiredstring

Allowed: png | jpg | webp | svg

Default: png

Notes: Selects output image format for generated T-Code.

logoOptionalstring

Allowed: data:image/...;base64,... under 2 MB

Notes: Optional image payload.

custom_fieldsRequiredarray

Allowed: Minimum 4 items; each item needs non-empty label + value

Notes: Rows can also include optional translations.

display_options.tcode_backgroundRequiredstring

Allowed: transparent | white

Default: transparent

Notes: Background style of T-Code.

display_options.tcode_colorRequiredstring

Allowed: #000000, #30acfd, #1e3a5f, #166534, #7f1d1d, #581c87, #374151, #78350f

Default: #000000

Notes: Only these hex values are accepted.

display_options.scan_text.enabledRequiredboolean

Allowed: true | false

Default: true

Notes: Turns the scan sentence on or off in the generated image.

display_options.scan_text.positionRequiredstring

Allowed: above | below

Default: below

Notes: Placement of scan message.

display_options.scan_text.alignmentRequiredstring

Allowed: left | center | right

Default: center

Notes: Horizontal alignment of scan message.

display_options.scan_text.use_customRequiredboolean

Allowed: true | false

Default: false

Notes: When false, the platform default sentence is used (see GUI scan text content).

display_options.scan_text.custom_textRequiredstring | null

Allowed: null or custom text

Default: null

Notes: Set to null when use_custom is false.

display_options.scan_text.colorRequiredstring

Allowed: #000000, #30acfd, #1e3a5f, #166534, #7f1d1d, #581c87, #374151, #78350f

Default: #000000

Notes: Scan line color in the generated image.

display_options.app_buttons.enabledRequiredboolean

Allowed: true | false

Default: false

Notes: Toggles app buttons in the generated image.

display_options.app_buttons.colorRequiredstring

Allowed: #000000, #30acfd, #1e3a5f, #166534, #7f1d1d, #581c87, #374151, #78350f

Default: #000000

Notes: Button color from the fixed palette.

display_options.app_buttons.styleRequiredstring

Allowed: filled | outlined

Default: filled

Notes: Button rendering style in generated image.

linked_documentOptionalobject

Allowed: If present, requires file_name + mime_type + data_base64; optional label, enable_label_translations, label_translations.en/de/fr

Notes: Encrypted attachment metadata and content.

T-Code display options in API interface

This is the dedicated display_options object used in API requests.

display_options.tcode_backgroundRequiredstring

Allowed: transparent | white

Default: transparent

Notes: Background style of generated T-Code.

display_options.tcode_colorRequiredstring

Allowed: #000000, #30acfd, #1e3a5f, #166534, #7f1d1d, #581c87, #374151, #78350f

Default: #000000

Notes: Only this fixed color set is accepted.

display_options.scan_text.enabledRequiredboolean

Allowed: true | false

Default: true

Notes: Turns scan sentence on or off.

display_options.scan_text.positionRequiredstring

Allowed: above | below

Default: below

Notes: Placement of scan text relative to T-Code.

display_options.scan_text.alignmentRequiredstring

Allowed: left | center | right

Default: center

Notes: Text alignment within the image block.

display_options.scan_text.use_customRequiredboolean

Allowed: true | false

Default: false

Notes: Enables custom sentence mode.

display_options.scan_text.custom_textRequiredstring | null

Allowed: null or custom text

Default: null

Notes: When custom mode is off, use null.

display_options.scan_text.colorRequiredstring

Allowed: #000000, #30acfd, #1e3a5f, #166534, #7f1d1d, #581c87, #374151, #78350f

Default: #000000

Notes: Uses the same fixed color palette.

display_options.app_buttons.enabledRequiredboolean

Allowed: true | false

Default: false

Notes: Toggles app buttons in generated image.

display_options.app_buttons.colorRequiredstring

Allowed: #000000, #30acfd, #1e3a5f, #166534, #7f1d1d, #581c87, #374151, #78350f

Default: #000000

Notes: Button color from fixed palette.

display_options.app_buttons.styleRequiredstring

Allowed: filled | outlined

Default: filled

Notes: Rendering style for app buttons.

How to place T-Code on a document

Option 1: API-driven workflow

  • Send a generate request with metadata, custom fields, and display options.
  • Receive the generated T-Code value and image format output.
  • Embed the returned code/image into your own document pipeline.
  • Use your own rendering rules for page position and size in your backend or DMS.

Option 2: GUI document upload workflow

  • Upload your document in the GUI interface.
  • Select T-Code position (preset corner/center or custom coordinates where available).
  • Set size and opacity/visibility style for the placed code.
  • Choose page scope: all pages, selected pages, range, odd/even, first/last (mode dependent).
  • Generate and download the final document with T-Code already embedded.

T-Code components and crypto flow

The current implementation builds a deterministic, fixed-length T-Code string. It first creates core components, then signs canonical messages with Ed25519, and finally appends signatures as base64url text.

Component lengths and meaning (full 270 chars)

  • version (2): hex value, default at start is 01. Used for format/version compatibility checks.
  • creator_id (7): creator namespace (example: TRYLH01). Allowed characters: uppercase letters, lowercase letters, and digits only ([A-Za-z0-9]). This ID is chosen during creator registration in LogiHash and is not changeable afterward.
  • db_entry_id (17): unique document/record reference.
  • dek_material (50): base64url text used to derive encryption key material.
  • kid (20): key identifier used to resolve the verification public key context.
  • policy_flags (2): hex value, default at start is 0F. Compact policy/config bits.
  • full_signature (86): Ed25519 signature (64 bytes) encoded as base64url.
  • header_signature (86): Ed25519 signature (64 bytes) encoded as base64url.

Verification format (134 chars)

  • Contains: version + creator_id + db_entry_id + kid + policy_flags + header_signature.
  • Excludes: dek_material and full_signature.
  • This is the value typically sent to verify/retrieve endpoints.

How signatures are created (current implementation)

  • Algorithm: Ed25519 (library: @noble/ed25519).
  • Input base: canonical packed UTF-8 fields with explicit length prefixes (len:value concatenation).
  • Domain separation prefixes:
    • LogiHash:TCode:FullSig:v1: for full signature.
    • LogiHash:TCode:HdrSig:v1: for header signature.
  • full_signature signs: version + creator_id + db_entry_id + dek_material + kid + policy_flags.
  • header_signature signs: version + creator_id + db_entry_id + kid + policy_flags.
  • Each 64-byte Ed25519 signature is base64url-encoded to ~86 chars and inserted into T-Code.

How encryption is used (current implementation)

  • Protected metadata encryption uses AES-256-GCM.
  • Key derivation input is dek_material, hashed with SHA-256 to a 32-byte AES key.
  • Encrypted blob format is IV(12 bytes) || ciphertext+tag, then base64url encoded.

Where each signature is used

  • header_signature: used in compact verification flow (134-char value) and fast authenticity checks.
  • full_signature: used when full 270-char T-Code is available and full integrity context is checked.
  • Verification recomputes the canonical message and calls Ed25519 verify with resolved public key (kid context).

Verify API request

Endpoint expects one body field:verification_value

Use the 134-character verification format (header verification value), not the full 270-character T-Code. The verification value contains:version,creator_id,db_entry_id,kid,policy_flags, and header_signature.

Verification first checks header-signature integrity and key context. If valid, the backend can return mapped metadata/linked-document context according to policy and availability.

Valid API request examples

Use these payloads as copy-ready templates for integration testing. Replace IDs, dates, and sample values with your own creator data.

Generate: /api/v1/tcode/generate

1) Minimal valid generate request (defaults)

{
  "creator_name": "LogiHash GmbH",
  "tcode_label": "INV-2026-0001",
  "address": {
    "street": "Bahnhofstrasse",
    "house_number": "1A",
    "postal_code": "8001",
    "city": "Zurich",
    "country": "CH"
  },
  "object_type": "Invoice",
  "valid_until": "2027-04-09",
  "output_image_format": "png",
  "custom_fields": [
    {
      "label": "Invoice No",
      "value": "INV-2026-0001"
    },
    {
      "label": "Customer",
      "value": "ACME Europe"
    },
    {
      "label": "Amount",
      "value": "CHF 4,250.00"
    },
    {
      "label": "Currency",
      "value": "CHF"
    }
  ],
  "display_options": {
    "tcode_background": "transparent",
    "tcode_color": "#000000",
    "scan_text": {
      "enabled": true,
      "position": "below",
      "alignment": "center",
      "use_custom": false,
      "custom_text": null,
      "color": "#000000"
    },
    "app_buttons": {
      "enabled": false,
      "color": "#000000",
      "style": "filled"
    }
  }
}

2) Generate request with custom scan text and app buttons

{
  "creator_name": "LogiHash GmbH",
  "address": {
    "street": "Bahnhofstrasse",
    "house_number": "1A",
    "postal_code": "8001",
    "city": "Zurich",
    "country": "CH"
  },
  "object_type": "Certificate",
  "valid_until": "2028-12-31",
  "output_image_format": "webp",
  "custom_fields": [
    {
      "label": "Certificate ID",
      "value": "CERT-2026-55"
    },
    {
      "label": "Issued To",
      "value": "Jane Doe"
    },
    {
      "label": "Program",
      "value": "Advanced Compliance"
    },
    {
      "label": "Hours",
      "value": "24"
    }
  ],
  "display_options": {
    "tcode_background": "white",
    "tcode_color": "#1e3a5f",
    "scan_text": {
      "enabled": true,
      "position": "above",
      "alignment": "left",
      "use_custom": true,
      "custom_text": "Scan to verify this certificate",
      "color": "#1e3a5f"
    },
    "app_buttons": {
      "enabled": true,
      "color": "#30acfd",
      "style": "outlined"
    }
  }
}

3) Generate request with linked document + label translations

{
  "creator_name": "LogiHash GmbH",
  "address": {
    "street": "Bahnhofstrasse",
    "house_number": "1A",
    "postal_code": "8001",
    "city": "Zurich",
    "country": "CH"
  },
  "object_type": "Contract",
  "valid_until": "2027-10-15",
  "output_image_format": "svg",
  "custom_fields": [
    {
      "label": "Contract No",
      "value": "CTR-10-2026"
    },
    {
      "label": "Counterparty",
      "value": "Northwind AG"
    },
    {
      "label": "Region",
      "value": "DACH"
    },
    {
      "label": "Signed At",
      "value": "2026-10-15"
    }
  ],
  "linked_document": {
    "file_name": "contract.pdf",
    "mime_type": "application/pdf",
    "data_base64": "<base64-encoded-file-content>",
    "label": "Original Contract",
    "enable_label_translations": true,
    "label_translations": {
      "en": "Original Contract",
      "de": "Originalvertrag",
      "fr": "Contrat original"
    }
  },
  "display_options": {
    "tcode_background": "transparent",
    "tcode_color": "#000000",
    "scan_text": {
      "enabled": true,
      "position": "below",
      "alignment": "center",
      "use_custom": false,
      "custom_text": null,
      "color": "#000000"
    },
    "app_buttons": {
      "enabled": false,
      "color": "#000000",
      "style": "filled"
    }
  }
}

Verify: /api/v1/tcode/verify-retrieve

1) Verify using compact verification value (recommended)

{
  "verification_value": "<134-char header value: version+creator_id+db_entry_id+kid+policy_flags+header_signature>"
}

2) Verify a scanned value from printed material

{
  "verification_value": "01TRYLH01A12B34C56D78E90F1KIDEXAMPLE00000000010Fh4Z8m8tN8qQ2fQ1fR9...<truncated>"
}

Authentication headers

  • Authorization: Bearer <API_KEY> — API credential for the caller.
  • X-Client-ID: <CREATOR_ID> — this value is the Creator ID.
  • Content-Type: application/json
  • Accept: application/json

API_KEY and CREATOR_ID are issued for the creator account. Requests with missing or mismatched credentials should be rejected by the API.