{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-embedded/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Licensing","siteUrl":"https://docs.synqly.com","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"synqly-embedded-licensing-guide","__idx":0},"children":["Synqly Embedded Licensing Guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide covers how to manage licenses for your Synqly Embedded deployment. You'll learn how to generate sub-licenses, inspect license files, verify licenses, and handle renewals."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Synqly Embedded container image includes built-in license management. All license operations — generating sub-licenses, inspecting license metadata, and verifying license validity — are performed using the same container image that runs your service. No additional tools are required."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Licenses use a two-level model:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Primary license"]}," — issued by Synqly for your organization. Contains your encrypted credentials and defines the maximum license duration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sub-license"]}," — generated by you from the primary license. Each sub-license is tied to a specific deployment instance and has its own expiration date (which cannot exceed the primary license expiration)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This model lets you provision time-limited individual deployments for your customers without contacting Synqly, while Synqly retains control over the overall license duration."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-youll-receive","__idx":2},"children":["What You'll Receive"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When Synqly provisions your license, you will receive two items:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A primary license file"]}," - a JSON file containing your license details and encrypted credentials."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A passphrase"]}," — this passphrase unlocks the credentials inside your primary license so you can generate sub-licenses for your customers when necessary."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep both items secure. Ideally, the primary license file and passphrase should not be stored together."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"quick-start","__idx":3},"children":["Quick Start"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Below shows the typical workflow from receiving your license to running a licensed deployment."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before running any of these commands, save the primary license as a JSON file to your current working directory with name ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primary-license.json"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["First, you can verify the validity of your primary license:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"docker run --rm \\\n  -v ./primary-license.json:/etc/synqly/license.json:ro \\\n  quay.io/synqly/embedded:latest \\\n  --license-verify /etc/synqly/license.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Next, you can generate a sub-license for customer. This will write the sub-license to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["licenses/"]}," directory in your current working directory."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# 1. Generate a sub-license for a specific deployment\nmkdir -p licenses\ndocker run --rm \\\n  -e SYNQLY_LICENSE_PASSPHRASE=\"$SYNQLY_PASSPHRASE\" \\\n  -v ./primary-license.json:/etc/synqly/primary-license.json:ro \\\n  -v ./licenses:/out \\\n  quay.io/synqly/embedded:latest \\\n  --license-generate /etc/synqly/primary-license.json \\\n  --license-expires 2027-06-01 \\\n  --license-instance-id prod-east-1 \\\n  --license-output /out/sub-license.json\n\n# 2. Verify the sub-license is valid\ndocker run --rm \\\n  -v ./licenses/sub-license.json:/etc/synqly/license.json:ro \\\n  quay.io/synqly/embedded:latest \\\n  --license-verify /etc/synqly/license.json\n\n# 3. Deploy the sub-license with the Embedded service\ndocker run \\\n  -v ./licenses/sub-license.json:/etc/synqly/license.json:ro \\\n  quay.io/synqly/embedded:latest\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each of these steps is explained in detail below."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"generating-a-sub-license","__idx":4},"children":["Generating a Sub-License"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--license-generate"]}," flag to create a sub-license from your primary license. The sub-license is what you deploy alongside the Embedded service. This is used when you deploy Embedded alongside your application in a customer environment, such as in an air gapped deployment. You should generate a unique sub-license for each of your on-prem customers that include Embedded."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The passphrase is read from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYNQLY_LICENSE_PASSPHRASE"]}," environment variable. This avoids exposing the passphrase in process listings or shell history."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Usage:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"docker run --rm \\\n  -e SYNQLY_LICENSE_PASSPHRASE=\"$SYNQLY_PASSPHRASE\" \\\n  -v ./primary-license.json:/etc/synqly/primary-license.json:ro \\\n  -v ./licenses:/out \\\n  quay.io/synqly/embedded:latest \\\n  --license-generate /etc/synqly/primary-license.json \\\n  --license-expires 2027-06-01 \\\n  --license-instance-id prod-east-1 \\\n  --license-output /out/sub-license.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Flags:"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Flag"},"children":["Flag"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--license-generate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Path to your primary license file (inside the container)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--license-expires"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Expiration date for this sub-license (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD"]}," format)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--license-instance-id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An identifier for this deployment (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["prod-east-1"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["staging"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--license-output"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Path to write the generated sub-license file (inside the container)"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Environment variables:"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Variable"},"children":["Variable"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYNQLY_LICENSE_PASSPHRASE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Passphrase provided by Synqly for the primary license"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rules:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The sub-license expiration date cannot be later than the primary license expiration date."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The sub-license expiration date cannot be in the past."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The primary license itself must not be expired."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The passphrase must match the one provided by Synqly."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"$ docker run --rm \\\n    -e SYNQLY_LICENSE_PASSPHRASE=\"correct-horse-battery-staple\" \\\n    -v ./primary-license.json:/etc/synqly/primary-license.json:ro \\\n    -v ./licenses:/out \\\n    quay.io/synqly/embedded:latest \\\n    --license-generate /etc/synqly/primary-license.json \\\n    --license-expires 2027-04-14 \\\n    --license-instance-id prod-east-1 \\\n    --license-output /out/prod-east-1-license.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On success, the sub-license is written to the output path and the container exits. On failure, a descriptive error message is printed and the container exits with a non-zero status code."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"inspecting-a-license","__idx":5},"children":["Inspecting a License"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--license-inspect"]}," flag to view the metadata of any license file (primary or sub-license) without starting the service. This is useful for checking expiration dates, license type, and deployment details."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Usage:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"docker run --rm \\\n  -v ./license.json:/etc/synqly/license.json:ro \\\n  quay.io/synqly/embedded:latest \\\n  --license-inspect /etc/synqly/license.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example output:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"License Information:\n  Type:        sub\n  License ID:  sub_a1b2c3d4e5f6\n  Parent ID:   lic_f6e5d4c3b2a1\n  Customer ID: cust_xyz\n  Instance ID: prod-east-1\n  Issued At:   2026-04-14T12:00:00Z\n  Expires At:  2027-04-14T23:59:59Z\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The inspect command never exposes private key material. It only displays the metadata fields that are safe to share."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"verifying-a-license","__idx":6},"children":["Verifying a License"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--license-verify"]}," flag to perform the same verification checks that the Embedded service runs on startup. This lets you confirm a license is valid before deploying it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Usage:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"docker run --rm \\\n  -v ./license.json:/etc/synqly/license.json:ro \\\n  quay.io/synqly/embedded:latest \\\n  --license-verify /etc/synqly/license.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What it checks:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The license signature is valid and has not been tampered with."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The license has not expired."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For sub-licenses: the key attestation is valid, and the sub-license expiration does not exceed the primary license expiration."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example output (valid license):"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"License verification: OK\n  Type:       sub\n  License ID: sub_a1b2c3d4e5f6\n  Expires At: 2027-04-14T23:59:59Z\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example output (invalid license):"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"License verification: FAILED\n  Error: license has expired\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The container exits with status code ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]}," on success and a non-zero status code on failure."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"deploying-a-license","__idx":7},"children":["Deploying a License"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have a valid sub-license, deploy it alongside the Embedded service by mounting it into the container."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"docker","__idx":8},"children":["Docker"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Mount the license file as a read-only volume at the default path ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/etc/synqly/license.json"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"docker run \\\n  -v ./prod-east-1-license.json:/etc/synqly/license.json:ro \\\n  quay.io/synqly/embedded:latest\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Or specify a custom path with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--license-file"]}," flag:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"docker run \\\n  -v ./prod-east-1-license.json:/opt/synqly/license.json:ro \\\n  quay.io/synqly/embedded:latest \\\n  --license-file /opt/synqly/license.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"docker-compose","__idx":9},"children":["Docker Compose"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"services:\n  embedded:\n    image: quay.io/synqly/embedded:latest\n    volumes:\n      - ./license.json:/etc/synqly/license.json:ro\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-happens-on-startup","__idx":10},"children":["What Happens on Startup"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the Embedded service starts with a license file configured:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The service loads and verifies the license before starting any other operations."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the license is valid, the service uses the license expiration date to govern its lifetime."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the license file is missing, unreadable, or fails verification, the service falls back to a 90-day expiration from the build date and logs a warning explaining why."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The service re-checks the license every 8 hours while running. If the license expires during operation, the service will shut down."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"license-expiration-and-renewal","__idx":11},"children":["License Expiration and Renewal"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"expiration-warnings","__idx":12},"children":["Expiration Warnings"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Embedded service monitors license expiration and provides advance warning:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["15 days before expiration:"]}," The service logs a warning on each periodic check (every 8 hours), alerting you that the license is approaching expiry."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["On expiration:"]}," The service shuts down."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These warnings appear in the service logs and in the audit trail, giving you time to renew before any disruption."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"checking-your-license-expiration","__idx":13},"children":["Checking Your License Expiration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can check when a license expires at any time without starting the service:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"docker run --rm \\\n  -v ./license.json:/etc/synqly/license.json:ro \\\n  quay.io/synqly/embedded:latest \\\n  --license-inspect /etc/synqly/license.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Look for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Expires At"]}," field in the output."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"renewal-workflow","__idx":14},"children":["Renewal Workflow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When your license is approaching expiration:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Contact Synqly"]}," to request a renewed primary license. Synqly will issue a new primary license with an updated expiration date."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Receive the new primary license and passphrase"]}," through the same secure delivery process as your original license."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Generate new sub-licenses"]}," from the renewed primary license for each of your deployments:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"docker run --rm \\\n  -e SYNQLY_LICENSE_PASSPHRASE=\"new-passphrase\" \\\n  -v ./new-primary-license.json:/etc/synqly/primary-license.json:ro \\\n  -v ./licenses:/out \\\n  quay.io/synqly/embedded:latest \\\n  --license-generate /etc/synqly/primary-license.json \\\n  --license-expires 2028-06-01 \\\n  --license-instance-id prod-east-1 \\\n  --license-output /out/new-sub-license.json\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify the new sub-license"]}," before deploying:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"docker run --rm \\\n  -v ./licenses/new-sub-license.json:/etc/synqly/license.json:ro \\\n  quay.io/synqly/embedded:latest \\\n  --license-verify /etc/synqly/license.json\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Replace the license file"]}," on each deployment and restart the container:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"cp ./licenses/new-sub-license.json ./license.json\ndocker restart embedded\n","lang":"bash"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The service will pick up the new license on its next startup."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting","__idx":15},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"private-key-decryption-failed","__idx":16},"children":["\"private key decryption failed\""]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The passphrase you provided does not match the one associated with your primary license."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Double-check the passphrase for typos, trailing whitespace, or encoding issues."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensure you are using the passphrase that was delivered alongside this specific primary license."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the passphrase is lost, contact Synqly to have a new primary license issued."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"license-has-expired","__idx":17},"children":["\"license has expired\""]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The license ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_at"]}," date has passed."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--license-inspect"]}," to check the expiration date."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Follow the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#renewal-workflow"},"children":["Renewal Workflow"]}," to obtain a new license."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"primary-license-has-expired","__idx":18},"children":["\"primary license has expired\""]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The primary license that was used to generate this sub-license has expired (the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primary_expires_at"]}," date has passed), even if the sub-license's own expiration has not."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Contact Synqly for a renewed primary license."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Generate a new sub-license from the renewed primary."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sub-license-expiration-exceeds-primary-expiration","__idx":19},"children":["\"sub-license expiration exceeds primary expiration\""]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The sub-license's expiration date is later than the primary license allows."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Regenerate the sub-license with an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--license-expires"]}," date that does not exceed the primary license expiration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--license-inspect"]}," on the primary license to check its expiration date."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"signature-verification-failed","__idx":20},"children":["\"signature verification failed\""]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The license file has been modified after it was signed. Even minor changes (whitespace, line endings) will break the signature."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensure the license file was transferred without modification (no line-ending conversion, no re-encoding)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the file is corrupted, regenerate the sub-license from your primary license."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"key-attestation-verification-failed","__idx":21},"children":["\"key attestation verification failed\""]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The sub-license was generated from a primary license that does not match the public key compiled into this binary."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensure you are using a primary license issued for this version of the Embedded binary."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Contact Synqly if you believe there is a key mismatch."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"service-falls-back-to-build-date-expiration","__idx":22},"children":["Service falls back to build-date expiration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The service logs a warning about using the 90-day build-date fallback instead of the license."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common causes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The license file is not found at the expected path (default: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/etc/synqly/license.json"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The license file has incorrect permissions (must be readable by the service process)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The license file does not match the public key compiled into the binary."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Resolution:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--license-file"]}," flag or verify the file exists at the default path."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check file permissions: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ls -la /etc/synqly/license.json"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Review the service logs for the specific verification error."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For Docker deployments, confirm the volume mount is correct: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["./license.json:/etc/synqly/license.json:ro"]},"."]}]}]},"headings":[{"value":"Synqly Embedded Licensing Guide","id":"synqly-embedded-licensing-guide","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"What You'll Receive","id":"what-youll-receive","depth":2},{"value":"Quick Start","id":"quick-start","depth":2},{"value":"Generating a Sub-License","id":"generating-a-sub-license","depth":2},{"value":"Inspecting a License","id":"inspecting-a-license","depth":2},{"value":"Verifying a License","id":"verifying-a-license","depth":2},{"value":"Deploying a License","id":"deploying-a-license","depth":2},{"value":"Docker","id":"docker","depth":3},{"value":"Docker Compose","id":"docker-compose","depth":3},{"value":"What Happens on Startup","id":"what-happens-on-startup","depth":3},{"value":"License Expiration and Renewal","id":"license-expiration-and-renewal","depth":2},{"value":"Expiration Warnings","id":"expiration-warnings","depth":3},{"value":"Checking Your License Expiration","id":"checking-your-license-expiration","depth":3},{"value":"Renewal Workflow","id":"renewal-workflow","depth":3},{"value":"Troubleshooting","id":"troubleshooting","depth":2},{"value":"\"private key decryption failed\"","id":"private-key-decryption-failed","depth":3},{"value":"\"license has expired\"","id":"license-has-expired","depth":3},{"value":"\"primary license has expired\"","id":"primary-license-has-expired","depth":3},{"value":"\"sub-license expiration exceeds primary expiration\"","id":"sub-license-expiration-exceeds-primary-expiration","depth":3},{"value":"\"signature verification failed\"","id":"signature-verification-failed","depth":3},{"value":"\"key attestation verification failed\"","id":"key-attestation-verification-failed","depth":3},{"value":"Service falls back to build-date expiration","id":"service-falls-back-to-build-date-expiration","depth":3}],"frontmatter":{"slug":"embedded/licensing","seo":{"title":"Licensing"}},"lastModified":"2026-05-06T16:33:16.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/embedded/licensing","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}