# Liminal Keys — full public documentation export Generated for assistants. Canonical site: https://www.liminalkeys.com --- # Docs Source: https://www.liminalkeys.com/docs/ # Liminal Keys documentation Production is the environment of record. All guides use liminalkeys.com hostnames. New here? Read the [product overview](/product/) and [pricing](/pricing/), then choose a path below. Liminal Keys supports two different signing workflows. **App & code signing** is for developers and build systems (Mac, Xcode, CI/CD, App Store). **AI agent signing** is for assistants and automations that sign documents or digests on a user’s behalf with policy and human approval. Shared setup lives under **Getting started & concepts**. ## Getting started & concepts For operators: workspaces, Console, identities, devices, policy, accounts, and security — before you wire Mac, CI, or agents. ### [Getting started Sign-up, service URLs, and the Console checklist.](/docs/getting-started/) ### [Console Identities, devices, CI & automation, policy, audit.](/docs/console/) ### [Linked sign-in methods Link IdPs when the same person uses multiple sign-in options.](/docs/console/linked-sign-in-methods/) ### [Security Custody model and what never leaves Key Vault.](/docs/security/) [Section overview →](/docs/concepts/) ## App & code signing For developers and release engineering: macOS app signing, pipelines (GitHub Actions and similar), App Store / notarization, and cross-platform CLI preview — not AI assistants. ### [macOS agent Liminal Keys for Mac, Xcode, codesign, enrollment.](/docs/macos/) ### [CI & pipelines OIDC, trusts, notarization, troubleshooting.](/docs/pipelines/) ### [CI quickstart Trusts checklist → signed build in GitHub Actions.](/docs/pipelines/quickstart/) ### [CI reference Trust form, Activity log, ASC broker.](/docs/pipelines/reference/) ### [Cross-platform CLI CLI install, setup-liminal-keys Action (preview).](/docs/pipelines/cli/) [Section overview →](/docs/app-signing/) · Customer story: [WatchTeams](/customers/watchteams/) ## AI agent signing For AI assistants and agent platforms: MCP connector (Claude and others), the liminalkeys-sign skill, PDF/document signing, and human approval via LK Approvals. Available in every workspace via Console **AI agents**. ### [Plugin vs skill vs MCP How the connector, skill, and Claude plugin fit together.](/docs/agents/concepts/) ### [AI agents & MCP URL-only OAuth, claude-plugin 0.1.10, signing flow.](/docs/agents/) ### [LK Approvals PWA install, push, approver inbox.](/docs/agents/approvals/) [Section overview →](/docs/agents/) ## Documentation for AI assistants You can point Claude, ChatGPT, Gemini, or other tools at our public text exports (mocked examples only; no tenant secrets): ``[/llms.txt](/llms.txt) (index, [llmstxt.org](https://llmstxt.org/) format) and ``[/llms-full.txt](/llms-full.txt) (public docs pages; no private repo internals). Each docs page also has a Markdown twin at the same path with `index.md` instead of `index.html`. > Private keys, PKCS#12 files, and enrollment secrets are never published on this site. Issue enrollment codes only in Console for your own tenant. --- # Getting started & concepts Source: https://www.liminalkeys.com/docs/concepts/ # Getting started & concepts For operators and security owners: create a workspace, manage identities and policy in Console, and understand how keys stay in custody. Pick a signing path after this section — [app & code signing](/docs/app-signing/) (Mac, CI, notarization) or [AI agent signing](/docs/agents/) (MCP, skills, human approval). ## [Getting started Sign-up, service URLs, Console checklist, and production API defaults.](/docs/getting-started/) ## [Console Identities, devices, CI & automation, policy rules, and sign audit.](/docs/console/) ## [Linked sign-in methods Link Microsoft, Google, and Apple sign-in for the same organization.](/docs/console/linked-sign-in-methods/) ## [Security Custody model, what never leaves Key Vault, and audit boundaries.](/docs/security/) [← All documentation](/docs/) --- # Getting started Source: https://www.liminalkeys.com/docs/getting-started/ Use production hostnames only. Local loopback APIs are for contributors, not customers. After signup, Console Overview shows a getting-started checklist (enroll → identity → allow policy → verify sign). Free beta soft caps: 2 identities / 2 signer nodes. Free during the beta, no card required. Paid plans (see [pricing](/pricing/)) start at the 1.0 release, with **60 days** to convert after the end-of-beta notice (paid self-serve Checkout is not enabled yet). Liminal Keys may send transactional email for signup confirmation, end-beta / conversion-grace notices, and billing issues (not marketing). ## Service URLs | Role | URL | `` | API | https://api.liminalkeys.com | ``[https://console.liminalkeys.com/?signup=1](https://console.liminalkeys.com/?signup=1)`` | Console | https://console.liminalkeys.com (use ?signup=1 for a new workspace) | ## Operator path - **Open Console** Open [Console sign-up](https://console.liminalkeys.com/?signup=1) (`console.liminalkeys.com/?signup=1`) and sign in with Microsoft work or school, Google, Apple, or **Sign in with email code** when shown on Console. GitHub is not offered. New users create a free beta workspace themselves — no invite or operator ticket required. - **Prepare an identity** Import a PKCS#12 into custody or generate a CSR, complete it with the issued certificate, then create policy rules (subjects, optional confirmation) and **Apply policy**. - **Issue an enrollment code** Create a short-lived enrollment code for the Mac that will sign. Treat it as a secret. - **Install Liminal Keys for Mac** Contractors can download without Console sign-in from [www.liminalkeys.com/download/mac/](/download/mac/). Admins can also use **Download Liminal Keys for Mac** (or copy the contractor install link) on Console Overview. - **Enroll the Mac** In Liminal Keys for Mac, set API URL to `https://api.liminalkeys.com`, paste the code, enroll, and refresh identities. For build agents and CI, use the headless Host CLI instead — see [CI & pipelines](/docs/pipelines/). - **Approve the Mac signing extension and sign** Allow the Liminal signing extension when macOS prompts. Sign with `codesign` or Xcode as usual (on-Mac confirmation prompts are coming soon). ## Headless enroll Build Macs and long-lived self-hosted runners use the bundled Host CLI (after installing from [download/mac](/download/mac/)). Always set the production API URL explicitly: ``` export LIMINAL_KEYS_API_BASE_URL=https://api.liminalkeys.com export LIMINAL_KEYS_ENROLLMENT_CODE='…from Console Devices…' liminal-keys enroll --json liminal-keys refresh --json ``` Ephemeral **GitHub Actions** CI uses OIDC and `LiminalKeys/liminal-keys-ci-sample/sign@v1` — not enrollment codes. Start from the public sample [Quickstart](https://github.com/LiminalKeys/liminal-keys-ci-sample#quickstart-zero--signed-build) or [CI & pipelines](/docs/pipelines/). *Console devices and enrollment where Mac enrollment codes are issued* Next (concepts): [Console](/docs/console/) · [Security](/docs/security/) App & code signing: [macOS agent](/docs/macos/) · [CI & pipelines](/docs/pipelines/) AI agent signing: [AI agents & MCP](/docs/agents/) --- # Console Source: https://www.liminalkeys.com/docs/console/ Administrative UI at [console.liminalkeys.com](https://console.liminalkeys.com). *Liminal Console identities view* ## Sign-in Console supports Microsoft work or school accounts, Google, and Apple. When your operator has enabled it, you may also use **Sign in with email code** for a Liminal Keys account (one-time passcode sent to your email). Choose **Sign in with Microsoft**, **Continue with Google**, or **Continue with Apple**. Social and Microsoft work paths open a brief Microsoft-hosted Liminal Keys page (address may show `ciamlogin.com`). If Microsoft federation is blocked by IT and email code is enabled for your environment, use the same address your invitation was sent to and enter the code from your email when prompted. After sign-in, Console checks your workspace once. If that fails, the screen offers **Retry workspace check** and **Sign out and try again**. Prefer Microsoft work or school if Google authorization keeps timing out; clear site data for console.liminalkeys.com only if sign-out alone does not help. Operators: pending API database migrations can also block workspace load — see product ops docs. Each provider is a separate Console identity until you link them explicitly. See [Linked sign-in methods](/docs/console/linked-sign-in-methods/) when the same person uses Microsoft, Google, or Apple with one email address. ## Signing identities Onboard signing identities whose private keys stay non-exportable in Key Vault: - **Import** — upload a password-protected PKCS#12 once; the private key is imported once into non-exportable Key Vault custody - **Generate** — create a key in custody, download a CSR, issue the certificate with Apple, then complete the identity - **Self-signed (testing)** — mint a short-lived self-signed leaf (up to one year) for agents and automation experiments. Console labels these identities as testing only — they are not trusted by PDF readers or mail clients. Pending, failed, or expired identities never appear on enrolled Macs and cannot be used in policy. Self-signed testing identities are active immediately; allow them in policy before agents call `sign_hash` or fetch `get_certificate_chain`. ## AI agents Register workspace agents (for example Claude Code connectors), set optional signing caps, and issue short-lived API keys. Keys are shown once at issue time — store them in your agent secret store immediately. Signing stays **deny by default** until a policy rule includes the agent as a subject. Suspend an agent to block new signs without revoking its enrollment device record. MCP setup: [AI agents & MCP guide](/docs/agents/) and Console → AI agents (connector URL + API keys). Use **Require approval** on agent rules when you want a human gate; approvers use the **LK Approvals** web app (optional web push). Liminal Keys is not a qualified trust service provider. *Liminal Console policy rules view* ## Policy rules Rules are the operational control plane for signing. Each rule specifies: - **Identity** — which virtual certificate may be used - **Subjects** — directory user, directory group, enrolled Mac, registered AI agent, or CI workload (trusted issuer / enrollment key). Rows of the same type are alternatives; different types must all match. CI workload subjects cannot require user confirmation; AI agents use **Require approval** for human gates. - **Operation** — sign (v1) - **Confirmation** — optional; not yet supported by the macOS agent (matching signs are denied — leave unchecked for now) - **Validity window** — optional start/end times - **Enabled** — disabled rules do not grant signs even after apply Edits are drafts until you click **Apply policy**. Until applied, a change MUST NOT grant signing. No matching applied rule means deny. If one applied rule would allow and another would deny the same request, the result is deny. ## CI & automation Configure GitHub OIDC trust (repository, runner type, optional branch/workflow/environment restrictions), CI enrollment keys, identity SHA-1 thumbprints for workflows, and recent CI enrollments. The tenant ID is also shown at the top of this page with **Copy**. Workflow YAML is maintained in the public sample repo [Quickstart](https://github.com/LiminalKeys/liminal-keys-ci-sample#quickstart-zero--signed-build). See [CI & pipelines](/docs/pipelines/). ## Devices & enrollment List enrolled Macs, revoke a machine that leaves the fleet, and issue short-lived enrollment codes for Liminal Keys for Mac. Treat codes as secrets — do not post them to shared mailing lists. Revocation stops signs from that device on the next request. ## Sign audit Review allow and deny outcomes with resolved device, identity, and rule names where available, plus timing. Each record includes **DigestHashHex** — the 64-character uppercase SHA-256 hash of the signed digest. The table shows the **first 16 hex characters** followed by …; use **Copy** for the full hash. Agent-initiated signs also show the agent-supplied document label. Raw 32-byte digest bytes, CMS signatures, and private key material are not stored or downloadable. ## Users & groups Invite people by email when they should sign in with Google, Apple, or another supported login. Create an invite link in Console, copy it, and share it yourself — Liminal Keys does not send invitation email. The invitee signs in, accepts the link, and is bound as a non-admin user. You can issue an enrollment code for a pending invitee so they enroll a Mac without opening Console. You can also add or update users and groups by identifier, and assign group membership, for policy subjects. Invites never grant tenant-admin access. ## Billing & usage Tenant administrators see **used vs soft cap** for signing identities and enrolled Mac signer nodes on the Billing page and on **Signing identities** and Devices when you are close to or at a cap. Counts come from the API (active and pending identities count toward the identity cap; enrolled Macs count toward the signer-node cap). Proximity hints such as “one slot remaining” help you plan add-ons or contact [support@liminalkeys.com](https://www.liminalkeys.com/contact/) before you hit a limit. ## Workspace settings Tenant administrators rename the workspace display name from **Workspace settings** (**Admin** in the sidebar; hash `#account`). The workspace **tenant ID** (lowercase UUID) appears on that page with **Copy** — use it as `LIMINAL_KEYS_TENANT_ID` / GitHub Actions `tenant-id` and in the OIDC audience `https://api.liminalkeys.com/t/`. ## Account settings Linked sign-in methods and explicit account linking live under **Account settings**, opened from the avatar menu in the top bar (`#profile`). Liminal Keys never links providers automatically — you confirm each connection. ## Platform (Liminal Keys operators) Accounts with the Liminal Keys platform-administrator role see an additional **Platform** view for customer tenants, beta-ops metrics, and payment/entitlement status — including which tenants are still on open beta versus in the **60-day conversion grace** after an end-beta notice. This is an operator surface, not a customer self-serve feature. ## Typical admin path Console navigation follows this configuration flow (Overview stays the default landing page): - Onboard an identity (import, generate + complete, or self-signed for testing) - Register agents under **AI agents** and store API keys - Add policy rules (subjects, optional approval, optional window) and **Apply policy** - Configure **CI & automation** trusts and/or enroll Macs under **Devices** - Invite users or sync directory subjects under **Users & groups** when rules need them - Watch Overview metrics and **Sign audit** for denials and successful signs [← Getting started](/docs/getting-started/) · [macOS agent →](/docs/macos/) --- # Linked sign-in methods Source: https://www.liminalkeys.com/docs/console/linked-sign-in-methods/ Use [Liminal Console](https://console.liminalkeys.com) → **Account** when you want more than one sign-in provider for the same organization. ## Default behavior (no silent merge) Microsoft work or school, Google, and Apple each create a **separate** Console identity until you explicitly link them. Signing in with a second provider that uses the same mailbox does **not** attach you to an existing Liminal Keys organization automatically — that protects your tenant from email-only account takeover. If you already created a workspace with Google and later sign in with Microsoft using the same email, Console asks you to sign in with Google again and link Microsoft from Account settings — or to confirm that you intentionally want a separate organization (discouraged). ## Link a second provider - Sign in with the provider you used to create the organization (for example Google). - Open **Account → Linked sign-in methods**. - Choose **Add sign-in method** and complete sign-in for Microsoft, Google, or Apple in the popup. - Confirm the link when both methods show the same verified email address. - Sign out and sign in with the second provider — you should reach the same tenant dashboard. ## Remove a method You can remove a linked provider when at least one other sign-in method remains. You cannot remove the method you are currently using — sign in with another linked provider first. ## When linking is not offered - **Different emails** — including Apple Hide My Email relays that do not match your primary mailbox — are treated as different people. Liminal Keys does not guess or merge them. - **Another organization** — if the second sign-in is the only administrator of a different entitled tenant, resolve that organization first or keep them separate. [← Console overview](/docs/console/) · [Getting started](/docs/getting-started/) --- # Security Source: https://www.liminalkeys.com/docs/security/ Private keys stay non-exportable and software-protected in Key Vault. The Mac holds public certs and device credentials only. Liminal Keys is **not a qualified trust service provider** (no QTSP / qualified electronic signature or seal services). ✓ ## Private keys remain in cloud custody Key Vault and database access stay behind Liminal. Console and Liminal Keys for Mac never receive private key bytes. *Console overview with cloud custody posture* ## Custody Signing private keys are held as non-exportable keys in Key Vault and every signature is made in cloud custody. The product path does not export private keys to administrators, the Console UI, or Liminal Keys for Mac as downloadable key material. - **Protection level (today):** keys are software-protected and non-exportable in Key Vault. Hardware security module (HSM) custody is on the roadmap and is not available today. - **Generated in Console (CSR):** the key is created inside Key Vault and never leaves it. - **Imported PKCS#12:** the key passes once through the Liminal API, in memory, on its way into Key Vault. After that it is non-exportable. ## What the Mac holds - Public certificate(s) for virtual identities - Device credential from enrollment (protect like a password) - Operational state for the Mac signing app (no private key bytes) ## What Console holds - Tenant and identity metadata - Policy configuration (rules, confirmation flags, validity windows) - Device enrollment state - Sign audit and signing approvals with **DigestHashHex** — the 64-character uppercase SHA-256 hash of the signed digest — plus outcome and identifiers. Console shows the first 16 hex characters with copy for the full value; LK Approvals shows a truncated hash. Not stored: raw 32-byte digest bytes, CMS signatures, private key material, or full document bytes. ## Electronic signatures and timestamps Liminal Keys helps you create **electronic signatures with your own certificate** (for example Apple code-signing identities you import or complete via CSR). We do not issue publicly trusted TLS or document certificates except short-lived **self-signed testing** leaves labelled as untrusted by PDF readers and mail clients. Signatures are **not** presented as handwriting-equivalent, admissibility-guaranteed, or eIDAS-qualified. Optional RFC 3161 document timestamps (for example via the agents MCP passthrough when configured) use a **third-party time-stamping authority**. Timestamping is **off by default**. When enabled, the default free TSA is **FreeTSA** — a **non-qualified** service with no presumption of legal time accuracy. ## AI agent approval Workspace AI agents sign through the same policy engine as Macs and CI. Policy rules can require **Require approval** before an agent sign proceeds; approvers act in the **LK Approvals** web app (optional web push). Pending approvals show the request label, optional preview images, and a truncated **DigestHashHex** (the server stores the full 64-character hash). Auto-sign and deny remain available. Agents never receive private key material. ## Authorization model Each sign is authorized only by **applied**, **enabled** policy rules for that tenant. A match requires identity, subject (user and/or group and/or device), operation (sign), and optional validity window. Missing context or no matching rule refuses the sign. On-Mac confirmation prompts are coming soon; currently, rules requiring confirmation deny matching signs. ## Transport and identity Production API and Console are served over HTTPS on liminalkeys.com hostnames. Console authentication uses Microsoft work or school accounts, Google, and Apple via Entra External ID for social sign-in. GitHub is not a Console IdP. Device enrollment uses short-lived codes issued by an authorized Console user. ## Enterprise options Available on request — use the same contact channel as product support. ### HSM support Hardware security module (HSM) support is on the roadmap. Contact us for more information or custom HSM integrations. [Contact us](https://www.liminalkeys.com/contact/) ### On-premises instance Self-hosted / on-premises deployment of Liminal Keys is available on request. [Contact us](https://www.liminalkeys.com/contact/) ## Hard limits - No injection into Apple system signing tools - Supported Mac path: Liminal Keys for Mac + virtual certificates for Xcode and `codesign` - Marketing pages never request or display secrets - Audit and approvals never store raw 32-byte digest bytes, CMS signatures, private key bytes, or full document bytes (SHA-256 digest hash hex may appear for correlation) [← macOS agent](/docs/macos/) · [All docs](/docs/) --- # App & code signing Source: https://www.liminalkeys.com/docs/app-signing/ # App & code signing For developers and build systems: sign apps, binaries, and release artifacts with certificates whose private keys stay in Key Vault. Covers Liminal Keys for Mac, `codesign` and Xcode, GitHub Actions and other CI, App Store upload, and notarization. Linux and Windows digest signing via the public CLI is **preview**. Not the AI agent path — see [AI agent signing](/docs/agents/) for MCP and document signing with approval. ## [macOS agent Liminal Keys for Mac, remote signing with Xcode or codesign, and status.](/docs/macos/) ## [CI & pipelines OIDC trusts, GitHub Actions, notarization, troubleshooting.](/docs/pipelines/) ## [CI quickstart Trusts checklist, GitHub variables, dry run → signed build.](/docs/pipelines/quickstart/) ## [CI reference Trust form, Activity log, ASC broker, enrollment keys.](/docs/pipelines/reference/) ## [Cross-platform CLI Public API install, setup-liminal-keys Action, ASC broker (preview).](/docs/pipelines/cli/) ## Customer story See how [WatchTeams](/customers/watchteams/) ships TestFlight builds on the Mac and in GitHub Actions — Key Vault custody, one policy, one audit. [← All documentation](/docs/) · [Getting started & concepts](/docs/concepts/) --- # macOS agent Source: https://www.liminalkeys.com/docs/macos/ Liminal Keys for Mac presents virtual certificates to macOS through its virtual smartcard. Private keys stay in cloud custody. *Console devices view used to enroll Mac hosts* ## What it does Liminal Keys for Mac holds the device credential from enrollment, talks to the production API, and makes virtual certificates available to macOS. When `codesign` or Xcode requests a signature, the digest is sent to cloud custody for signing. The Mac keeps public certificates and device credentials only — never private key bytes. ## Install Liminal Keys for Mac - Download the notarized package from the public page [www.liminalkeys.com/download/mac/](/download/mac/) (no Console sign-in), or use **Download Liminal Keys for Mac** in Console as an admin - Open the DMG, drag **Liminal Keys for Mac** (the app file is `Liminal Keys Virtual Smartcard.app`) to Applications - Gatekeeper should allow a normal double-click for notarized builds — use Open anyway only if macOS still prompts - Enroll with a one-time enrollment code from your administrator (Devices in Console) Customers do **not** build from source. Download does not enroll the Mac — a valid, unconsumed enrollment code is still required. ## Enrollment (Host UI) - In Console, open **Devices** and issue an enrollment code - In Liminal Keys for Mac, set **API URL** to `https://api.liminalkeys.com` - Paste the enrollment code, complete enroll, then refresh identities - Approve the Liminal signing extension in System Settings if macOS prompts ## Enrollment (Host CLI) For build Macs and CI, use the bundled Host CLI located at: ``` /Applications/Liminal\ Keys\ Virtual\ Smartcard.app/Contents/Helpers/LiminalKeysHostCLI ``` You can optionally create a symlink to put it on your PATH (run manually; the app does not modify system directories): ``` sudo ln -s "/Applications/Liminal Keys Virtual Smartcard.app/Contents/Helpers/LiminalKeysHostCLI" /usr/local/bin/liminal-keys ``` Set the production API URL explicitly and run enrollment: ``` export LIMINAL_KEYS_API_BASE_URL=https://api.liminalkeys.com export LIMINAL_KEYS_ENROLLMENT_CODE='…from Console…' liminal-keys enroll --json liminal-keys status --require-enrolled --json ``` Details: [CI & pipelines](/docs/pipelines/). Prefer environment variables for enrollment codes so they do not appear in shell history or committed scripts. ## Signing with codesign and Xcode After identities appear, use your normal signing workflow. Select the Liminal virtual identity where you would select a local certificate. The extension presents the public cert; the private operation happens in cloud custody (Key Vault) through the API. ## Sign confirmation Sign confirmation prompts are **not yet available** in the macOS agent. If a Console policy rule has **Require user confirmation** enabled, matching signs are denied and recorded in audit. Leave confirmation unchecked until the agent supports prompts. ## Troubleshooting checklist If signing or extension registration encounters issues, run the built-in diagnostic tool first: ``` /Applications/Liminal\ Keys\ Virtual\ Smartcard.app/Contents/Helpers/LiminalKeysHostCLI doctor ``` The `doctor` command verifies enrollment, API health, virtual smartcard registration, extension election, keychain isolation, policy permission, and runs a scratch signing probe. - API reachable: `curl -s https://api.liminalkeys.com/health` should return OK - Enrollment code not expired or already consumed - Policy applied in Console after identity or rule changes - Token extension enabled for the user session - Host shows Connected and lists the expected certificate - Leave **Require user confirmation** unchecked (not supported yet — matching signs are denied) - If **Refresh identities** fails, use **Copy** on the error panel when contacting support > Never paste private keys, PKCS#12 files, or long-lived enrollment secrets into support tickets or public channels. Rotate enrollment codes if exposure is suspected. [← Console](/docs/console/) · [CI & pipelines](/docs/pipelines/) · [Security →](/docs/security/) --- # CI & pipelines Source: https://www.liminalkeys.com/docs/pipelines/ # CI & pipelines Companies keep control of certificates and signing keys in **Key Vault**, while agencies and contractors build and release under the company’s policy. Sign Apple apps in GitHub Actions with short-lived CI devices and GitHub OIDC — no stored enrollment codes or signing secrets. Production API: `https://api.liminalkeys.com`. Private keys stay non-exportable in Key Vault; they never reach the runner. [WatchTeams](/customers/watchteams/) 2.1.0 (Devfinition) was signed through this CI path and shipped to the App Store (ephemeral CI device, no smart card on the runner). [Customer story →](/customers/watchteams/) > **Preview:** cross-platform `liminal-keys` `0.1.x` installs from the public API or [setup-liminal-keys](https://github.com/LiminalKeys/setup-liminal-keys) — see [Cross-platform CLI](/docs/pipelines/cli/). Linux and Windows digest signing: **Preview**. Supported today: self-hosted macOS with the Liminal Keys Mac app. GitHub-hosted macOS: being verified. ## Choose a path | Path | Best for | **** ```` | GitHub Actions + OIDC (below) | Self-hosted macOS runners with the Liminal Keys Mac app; sign@v1 enroll + export@v1 for App Store IPA (no private repo checkout) | **** `````` | GitHub-hosted macOS (being verified) | Ephemeral macos-* runners — use install-host on sign@v1 (see below); not supported for production use until verified | **** `` | CI enrollment key | Runners without OIDC — scoped lkci_ secret (lower assurance than OIDC) | **** ``[#self-hosted](#self-hosted) | Persistent self-hosted Mac | Long-lived build Mac with interactive enroll and LiminalKeysHostCLI enroll — see Self-hosted Mac | ## Console setup Step-by-step guides: [CI quickstart](/docs/pipelines/quickstart/) · [CI reference](/docs/pipelines/reference/) · [Cross-platform CLI (preview)](/docs/pipelines/cli/) (full markdown also in the [llms-full.txt](/llms-full.txt) or the public docs pages below). In [Liminal Console](https://console.liminalkeys.com) open **CI & automation** — tabs **Trusts**, **Activity**, and **Enrollment keys**. The **Set up CI signing** checklist on **Trusts** tracks three steps: - **Add a GitHub trust** — pin one repository (for example `acme-corp/acme-ios`) with required **branch or tag**, **workflow file**, and at least one **identity in scope**. Incomplete trusts return **400**; duplicate trust names return **409**. - **Allow it in a policy rule** — **Policy rules** → Allow / **sign** → subject **CI workload (trusted issuer)** → your trust → **Apply policy**. - **Run your workflow** — set `LIMINAL_KEYS_TENANT_ID` and `LIMINAL_KEYS_CERT_SHA1` as repository variables, then run the sample dry-run workflow. Refused enrollments appear under **Activity** — open the refusal drawer for reason codes and **Expected** vs **Got**. Use **Create trust from this run** or **Paste claims from a test run** on Add trust to prefill fields from verified run data (OIDC JWT is verified once and not stored). *Console CI and automation Trusts tab with setup checklist (mocked data)* ## GitHub Actions (self-hosted macOS runners) Copy workflow YAML from the public sample repo [Quickstart (zero → signed build)](https://github.com/LiminalKeys/liminal-keys-ci-sample#quickstart-zero--signed-build) — dry-run template, `sign-sample.yml`, `app-store-release.template.yml`, Developer ID notarization template, and troubleshooting. Do not maintain a second copy in your docs; fork the sample patterns instead. Every OIDC job needs `permissions: id-token: write` and `contents: read`. Token audience: `https://api.liminalkeys.com/t/` (lowercase tenant UUID from Console). Action input `ttl-minutes` maps to Host CLI `--ttl` (for example `60m`). On **self-hosted macOS runners** (supported today), run `LiminalKeys/liminal-keys-ci-sample/sign@v1` with the Liminal Keys Mac app available on the runner. The step enrolls a short-lived CI device, runs a sign readiness check, and always attempts unenroll in a post step. Outputs include `signing-sha1`, `device-id`, and `expires-at` (also `LIMINAL_KEYS_SIGNING_SHA1` in job env). **GitHub-hosted macOS runners (being verified).** On ephemeral GitHub-hosted `macos-*` runners, set the Action input `install-host` so `sign@v1` installs **Liminal Keys for Mac** on the runner before enroll. This path is being verified — do not treat GitHub-hosted runners as supported for production until we publish verification. ### Signing tips - Sign nested frameworks and helpers first, then the app — do not use `codesign --deep`. - Virtual identities may not appear in `security find-identity`; use the Console SHA-1 with `codesign -s`. - Use `--options runtime` and `--timestamp` for distribution builds. For example, [WatchTeams](/customers/watchteams/) 2.1.0 (Devfinition) was signed through this CI path and shipped to the App Store. - Pass secrets only via `env:` in shell steps — never expand `${{ secrets.* }}` inside `run:` script text. ## macOS app notarization (your credentials) **macOS app** notarization (DMG, pkg, or notarized Mac app bundles) runs **after** Liminal Keys signing and does **not** need an active CI device. Store your App Store Connect API key in **your** GitHub secrets (`ASC_KEY_ID`, `ASC_ISSUER_ID`, `ASC_KEY_P8` or `ASC_KEY_P8_BASE64`). Apple lets you download the `.p8` **only once** at key creation — save it in secrets immediately. **Liminal Keys never sees or stores your App Store Connect private key.** Sign the payload, submit with `xcrun notarytool`, then `xcrun stapler staple`. See Apple’s [notarization documentation](https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution). This section applies only to optional **macOS app** notarization steps (not iOS App Store releases such as WatchTeams 2.1.0). ## CI enrollment keys (no OIDC) On **CI & automation**, create a **CI enrollment key**, copy the one-time `lkci_…` secret into `LIMINAL_KEYS_CI_KEY` (GitHub secret / env only), and point the sign Action at your tenant and SHA-1. Prefer GitHub OIDC when available — OIDC uses per-job tokens with replay protection; shared CI keys are easier to misuse if leaked. ``` - uses: LiminalKeys/liminal-keys-ci-sample/sign@v1 env: LIMINAL_KEYS_CI_KEY: ${{ secrets.LIMINAL_KEYS_CI_KEY }} with: tenant-id: ${{ vars.LIMINAL_KEYS_TENANT_ID }} identity-sha1: ${{ vars.LIMINAL_KEYS_CERT_SHA1 }} ``` ## Security & limits - Each job gets a short-lived CI device enrolled with GitHub OIDC or a CI key. - Signing calls the cloud API; private keys remain in Key Vault custody. - Default CI device lifetime: **60 minutes** (request **5–120** with `ttl-minutes` / `--ttl`). - Concurrent CI devices: **2** during beta, **5** on paid plans (trust-level caps may lower this). - Audit: **Sign audit** lists each signing operation; match **CI device** id from Action output `device-id`. **CI & automation → Activity** lists enrollments and refusals with run links when available. ## Troubleshooting | Issue | Check | ``| OIDC / id-token errors | permissions: id-token: write; fork PRs often cannot mint tokens | ******| Enrollment refused / 403 The identity token was refused. | Activity refusal drawer — branch, workflow file, repository, or environment mismatch; edit trust or run from allowed branch/workflow | ********| Sign denied | Policy rule for CI workload (trusted issuer); click Apply policy | ``| CI device cap | Wait for TTL expiry or finish jobs so ci unenroll runs | | sign-check fails | Re-run; identity SHA-1 in trust scope; smartcard token enabled on runner | ## Self-hosted Mac (persistent runner) Install **Liminal Keys for Mac** on a dedicated build Mac, enroll once with an enrollment code from **Console → Devices**, then use `LiminalKeysHostCLI enroll`, `refresh`, and `status` with `LIMINAL_KEYS_API_BASE_URL=https://api.liminalkeys.com`. Policy subjects use an enrolled **device**, not CI workload types. This path is separate from short-lived CI devices on GitHub Actions — do not store enrollment codes in workflow secrets for CI signing. ## Other platforms (coming later) GitLab, CircleCI, Bitrise, and AWS macOS capacity are not covered by copy-paste recipes yet. Google Cloud Build has no macOS workers. Use CI enrollment keys on a self-hosted Mac agent until a first-party wrapper ships. > Never commit enrollment codes, CI keys, OIDC tokens, or App Store Connect `.p8` material. ## Further reading - [When CI ships your iPhone app, who holds the signing key?](https://medium.com/@liminalkeys/when-ci-ships-your-iphone-app-who-holds-the-signing-key-79c67c2ee328) (Medium, Liminal Keys) - [Your release pipeline signs your app. Does it need to hold the key?](https://www.linkedin.com/pulse/your-release-pipeline-signs-app-does-need-hold-key-devfinition-6zype/) (LinkedIn, Devfinition) More essays and announcements: [Articles on liminalkeys.com](/articles/). Related: [Getting started](/docs/getting-started/) · [Liminal Keys for Mac](/docs/macos/) · [Console](/docs/console/) --- # CI quickstart Source: https://www.liminalkeys.com/docs/pipelines/quickstart/ Go from zero to a signed build with GitHub OIDC, Console **CI & automation**, and the public [sample Quickstart](https://github.com/LiminalKeys/liminal-keys-ci-sample#quickstart-zero--signed-build). Deeper detail: [CI reference](/docs/pipelines/reference/). ## Console: Set up CI signing Open **CI & automation** — tabs **Trusts**, **Activity**, **Enrollment keys**. Complete all three checklist steps on **Trusts**: - **Add a GitHub trust** - **Allow it in a policy rule** (Apply policy) - **Run your workflow** with tenant ID and identity SHA-1 variables *Trusts tab with Set up CI signing checklist (mocked data)* ## Add GitHub trust (required fields) Example mock repo `acme-corp/acme-ios`, trust name **Acme iOS TestFlight release**. - **Repository** — plain text `owner/name` (not a URL) - **Repository numeric ID** — required; OIDC claim `repository_id` - **Branch or tag** — e.g. `refs/heads/main` - **Workflow file** — glob for your release workflow - **At least one identity in scope** ``` gh api repos/acme-corp/acme-ios --jq .id ``` Incomplete saves return **400**; duplicate trust names return **409**. Detail: [CI reference](/docs/pipelines/reference/). ## GitHub variables `LIMINAL_KEYS_TENANT_ID`, `LIMINAL_KEYS_CERT_SHA1`, and `permissions: id-token: write`. For ASC broker uploads add `LIMINAL_KEYS_ASC_KEY_ID` (Liminal UUID after key import). ## Dry run Copy `liminal-keys-dry-run.yml` from the sample repo, run on an allowed branch, confirm **Activity** shows **enrolled**. Related: [CI overview](/docs/pipelines/) · [CI reference](/docs/pipelines/reference/) · [Getting started](/docs/getting-started/) --- # CI reference Source: https://www.liminalkeys.com/docs/pipelines/reference/ Quick path: [CI quickstart](/docs/pipelines/quickstart/) · CLI preview: [Cross-platform CLI](/docs/pipelines/cli/). ## GitHub trust form Enter the repository as plain text `owner/name` (for example `acme-corp/acme-ios`). Private customer repos are normal — you do not need GitHub’s repository lookup to succeed before save. **Repository numeric ID** is required. GitHub puts this number in OIDC tokens as `repository_id`. Repo Settings does not show it — use GitHub CLI when you have access: ``` gh api repos/acme-corp/acme-ios --jq .id ``` Other required fields: trust name (unique per workspace), branch or tag, workflow file glob, and at least one identity in scope. Incomplete saves return **400**; duplicate trust names return **409**. *Trust form validation (mocked data)* ## Activity and refusal drawer The **Activity** tab lists enrollments, refusals, and App Store Connect token events. Open a refused row for reason codes and **Expected** vs **Got**. *Activity refusal drawer with expected vs got (mocked data)* ## Activity: `asc_token_issued` When CI mints an upload token, Activity shows **Token issued** (`asc_token_issued`) with the trust, run link, and key reference — not the JWT. Tokens are short-lived (about **10 minutes**). Refused mints use separate ASC reason codes (for example no allow rule or policy not applied). *Activity log including token events (mocked data)* ## Prefill from runs and pasted claims - **Create trust from this run** — from Activity, prefill Add trust from verified audit fields. - **Paste claims from a test run** — verify a workflow OIDC JWT once; token is not stored. *Create trust from this run button (mocked data)* ## Policy: Issue App Store Connect upload tokens Separate from signing rules: in **Policy rules**, choose **Issue App Store Connect upload tokens**, pick an imported ASC key, subject **CI workload (trusted issuer)**, bind your GitHub trust, then **Apply policy**. CI passes the Liminal key UUID as `LIMINAL_KEYS_ASC_KEY_ID`. *Policy rule step when a trust still needs a rule (mocked data)* Import keys in Console **CI & automation → App Store Connect keys** or with `liminal-keys admin asc import` (see [CLI reference](/docs/pipelines/cli/)). Prefer **App Manager** team keys in App Store Connect for upload-only CI. ## Enrollment keys tab When OIDC is unavailable, create a scoped `lkci_…` key and pass `LIMINAL_KEYS_CI_KEY`. Prefer OIDC on GitHub Actions. ## Second app, same distribution certificate Reuse the same certificate SHA-1; add a **new GitHub trust** and **policy rule** per repository; create a new Apple provisioning profile per bundle ID. ## ASC broker vs legacy `.p8` on the runner **Recommended:** import the `.p8` once (Console or admin CLI); CI mints tokens — no `ASC_KEY_P8` secret on the runner. Smoke test: [asc-broker-smoke.yml](https://github.com/LiminalKeys/liminal-keys-ci-sample/blob/main/.github/workflows/asc-broker-smoke.yml) in the sample repo. **Fallback:** store `ASC_KEY_ID`, `ASC_ISSUER_ID`, and `ASC_KEY_P8` in GitHub secrets for `xcrun altool` / notarization templates (`asc_upload_mode: p8-altool` in some release workflows). Liminal Keys does not store your `.p8` unless you use admin import. Related: [CI overview](/docs/pipelines/) · [CI quickstart](/docs/pipelines/quickstart/) · [Cross-platform CLI](/docs/pipelines/cli/) --- # Cross-platform CLI (preview) Source: https://www.liminalkeys.com/docs/pipelines/cli/ Headless digest signing and the **App Store Connect upload broker** on Linux, Windows, and macOS runners. Mac `codesign` via Virtual Smartcard still uses the Host app and [sign@v1](https://github.com/LiminalKeys/liminal-keys-ci-sample). Related: [CI reference](/docs/pipelines/reference/) · [CI quickstart](/docs/pipelines/quickstart/). > **Preview:** CLI `0.1.x` installs anonymously from the public API (`GET /v1/public/cli/versions/{version}`) or the [setup-liminal-keys](https://github.com/LiminalKeys/setup-liminal-keys) Action — no GitHub token. Pin semver and SHA-256 per runner OS/arch. Mac `codesign` still uses the Host app and `sign@v1`. ## Install (GitHub Actions) Pin `version` and `sha256` for this runner (example: `0.1.10`, Ubuntu x64). Metadata: `https://api.liminalkeys.com/v1/public/cli/versions/0.1.10`. ``` - uses: LiminalKeys/setup-liminal-keys@v1 with: version: "0.1.10" sha256: "c9495db59e9433fcb2ac118b9a4e7d18421714da7d42780a39f6af9899c711d5" ``` ## Install (manual / curl) Download via the API asset URL, verify SHA-256 against metadata, then add to `PATH` (Windows: `liminal-keys-win-x64.exe`). ``` curl -fsSL "https://api.liminalkeys.com/v1/public/cli/versions/0.1.10/assets/liminal-keys-linux-x64/download" -o liminal-keys shasum -a 256 liminal-keys # expect c9495db59e9433fcb2ac118b9a4e7d18421714da7d42780a39f6af9899c711d5 chmod +x liminal-keys ``` ## Tenant admin (`admin`) Sign in with the dedicated CLI public client (CIAM user flow — not the Console SPA). Session is stored locally for subsequent admin commands. ``` liminal-keys admin login ``` ``` liminal-keys admin logout ``` ### Workspace tenant id ``` liminal-keys admin platform me ``` Requires an linked workspace. Use the printed tenant GUID for `LIMINAL_KEYS_TENANT_ID` and OIDC audience `https://api.liminalkeys.com/t/`. ASC key import requires **Active** or **Comped** entitlement on your workspace (see Console Billing). ## App Store Connect keys In App Store Connect → Users and Access → Keys, create a key with access to upload builds. For **team** keys we recommend the **App Manager** role (enough for uploads). **Admin** keys also manage users and settings CI does not need. Liminal Keys cannot read a key’s role — confirm in App Store Connect. Download the `.p8` **once**. Import reads the file from disk and never prints key material. Choose `--key-type team` or `individual`. Console import supports **Check with Apple** before save; the CLI validates format on upload. ``` liminal-keys admin asc import --file ~/Downloads/AuthKey_ABCDE12345.p8 --key-id ABCDE12345 --issuer-id 00000000-0000-0000-0000-000000000000 --key-type team --display-name "Acme iOS upload" ``` Note the returned Liminal key UUID (`66666666-7777-8888-9999-aaaaaaaaaaaa` in examples). ### Allow mint (policy rule) In Console **Policy rules**, choose **Issue App Store Connect upload tokens**, pick the imported key, subject **CI workload (trusted issuer)**, select your GitHub trust, then **Apply policy**. Or draft the same allow rule from the CLI: ``` liminal-keys admin asc allow-mint --asc-key-id 66666666-7777-8888-9999-aaaaaaaaaaaa --ci-trust-id bbbbbbbb-cccc-dddd-eeee-ffffffffffff --apply ``` ### CI: mint and upload After enroll, mint a JWT valid for about **10 minutes** (`expMinutes=10`). Successful mints appear in **Activity** as `asc_token_issued` (masked token metadata — not the JWT). ``` liminal-keys asc token --asc-key-id 66666666-7777-8888-9999-aaaaaaaaaaaa --json ``` ``` liminal-keys upload --ipa dist/Acme.ipa --bundle-id com.example.acme ``` Set repository variable `LIMINAL_KEYS_ASC_KEY_ID` to the Liminal UUID from import (not Apple’s 10-character Key ID). ## CI enroll and sign (digest) ``` liminal-keys ci enroll --tenant-id 11111111-2222-3333-4444-555555555555 --ttl 60m --identity --json ``` ``` liminal-keys sign --identity --file dist.bin ``` ``` liminal-keys ci unenroll --json ``` Always run `ci unenroll` in a final step with `if: always()`. Requires `permissions: id-token: write` for GitHub OIDC. ## Sample workflows [ASC broker smoke](https://github.com/LiminalKeys/liminal-keys-ci-sample/blob/main/.github/workflows/asc-broker-smoke.yml) (Ubuntu: enroll → mint → Apple GET /v1/apps). Release templates may expose `asc_mint_smoke_only` to run mint checks without a full archive, and `asc_upload_mode: p8-altool` as a legacy fallback when the broker path is unavailable. Related: [CI overview](/docs/pipelines/) · [CI reference](/docs/pipelines/reference/) --- # AI agents & MCP Source: https://www.liminalkeys.com/docs/agents/ # AI agents & MCP connector **AI agent signing** — not Mac/Xcode or CI app signing (see [App & code signing](/docs/app-signing/)). Workspace AI agents (for example Claude) sign through the same policy engine as other signers, with optional human approval. Private keys stay in Key Vault; agents never receive key material. Open **Console → AI agents** to register connectors and issue API keys. New here? Read [Plugin vs skill vs MCP connector](/docs/agents/concepts/) first. ## MCP connector URL Streamable HTTP endpoint (production): ``` https://mcp.liminalkeys.com/mcp ``` Console → **AI agents** shows the same URL with a copy button. Response envelopes are ES256-signed; public keys are at `https://mcp.liminalkeys.com/.well-known/liminalkeys-mcp-keys.json` (kid `mcp-response-v1`). ## Claude setup (plugin 0.1.10) The recommended path is the official **Liminal Keys** Claude plugin (**liminal-keys** 0.1.10). It installs the **liminalkeys-sign** skill and wires the MCP connector to `https://mcp.liminalkeys.com/mcp`. ### Connect the MCP server (URL only) Add the MCP URL above in Claude and choose **Connect**. Sign in with your **Liminal Keys account** (Google, Apple, Microsoft work or school, or email code — the same options as Console). Authentication uses **URL-only OAuth** with automatic client registration: you do **not** paste a client ID, client secret, or other OAuth app credentials in advanced settings. If you have multiple AI agents in Console, pick which connection this connector should use when prompted. ### Claude Code Add the marketplace, install or update the plugin, then start a session: ``` /plugin marketplace add LiminalKeys/claude-plugin /plugin install liminal-keys@liminal-keys ``` To upgrade an existing install, run the same `install` command again after refreshing the marketplace. ### claude.ai - Open **Customize → Plugins**. - Add or **refresh** the GitHub marketplace **LiminalKeys/claude-plugin**. - Enable the **Liminal Keys** plugin and connect the bundled MCP URL with **Connect** (URL-only sign-in as above). ### Skill zip without the plugin Same skill version the plugin bundles (offline wheels, SHA-256 sidecar): - [liminalkeys-sign-skill-0.1.10.zip](/downloads/liminalkeys-sign-skill-0.1.10.zip) - [liminalkeys-sign-skill-0.1.10.zip.sha256](/downloads/liminalkeys-sign-skill-0.1.10.zip.sha256) Upload the zip in Claude Skills, or extract and point the sandbox at the inner `liminalkeys-sign/` folder. ### Optional: API key header (non-OAuth clients) Some hosts do not support MCP OAuth yet. You can send a Console-issued `lkag_…` key in `x-api-key` instead (one auth mode per request — not both OAuth and a key). Issue a **30- or 90-day** key in Console → **AI agents** if you use this path. ## MCP tools (four) - `list_certificates` — allowed signing certificates (`client_nonce` required) - `get_certificate_chain` — chain envelope + leaf PEM (`certificate_id`, `client_nonce`) - `sign_hash` — RSA signature over a 32-byte digest (`digest_base64`, `document_label`, `client_nonce`; optional `approval_id`, `poll_timeout_seconds` 0–120 default 120, `previews`) - `timestamp` — optional RFC 3161 via FreeTSA (non-qualified, off unless requested) `prepare`, embed, and validate run locally via **liminal-sign** — not as MCP tools. ## Signing flow (liminalkeys-sign 0.1.10) One certificate lookup per attempt, then prepare → sign → finish. Do not re-list certificates or re-fetch the chain mid-flow. - 1 ### MCP: certificates (once each) `list_certificates` with `client_nonce`, then `get_certificate_chain` with a new nonce. Save chain PEM locally (for example `chain.pem`). - 2 ### Local: prepare ``` liminal-sign prepare --pdf "$PDF" --cert-chain chain.pem \ --out state.json --document-label "Contract Q4" ``` Hashes the PDF in the sandbox, builds approval previews, and prepares CMS state. Use `digest_base64` and `previews` from `state.json` on `sign_hash`. - 3 ### MCP: sign_hash (one approval when required) Call once with the same `client_nonce` from step 1. Long-poll up to **120 seconds**. When policy requires approval, approvers act in [LK Approvals](/docs/agents/approvals/) or on their phone. **Resume:** After approval, if the call times out or returns `pending_approval`, call `sign_hash` again with the **same** `digest_base64`, `client_nonce`, and `approval_id`. That collects the signature — it does **not** create a second approval. Never mint a new nonce after approval. - 4 ### Local: finish ``` liminal-sign finish --state state.json --mcp-sign-envelope sign.json \ --expected-nonce "$NONCE" --output signed.pdf ``` Embeds the signature, runs mandatory validation, and prints the report. Non-zero exit means not successfully signed. ### Branded visible stamp (default) Skill **0.1.10** adds a branded Liminal Keys stamp by default: **last page**, **bottom-right**, **248×96** pt, with dates in the signer’s **local timezone** (override with `--stamp-locale` / `--stamp-timezone` on `prepare`). For a cryptographic signature with no on-page mark, add `--invisible-signature` on `prepare`. ### Approvals and previews When policy requires approval, include at least one small PNG in `sign_hash` `previews` on the **first** call — `prepare` supplies these in `state.json`. Previews are agent-rendered context for approvers (unverified). See [LK Approvals](/docs/agents/approvals/). ## Console setup - Open [Console](https://console.liminalkeys.com) → **AI agents**. - Create an agent (for OAuth connector binding and optional API keys). - In **Policy rules**, add a rule with subject type **AI agent** and allow, require approval, or deny. - Review outcomes in **Sign audit** (document label and **DigestHashHex** — first 16 hex characters in the table, copy for the full 64-character SHA-256 hash). ## Sample prompts | Prompt | Flow | ````| List the signing certificates my Liminal Keys agent is allowed to use, with subject and expiry. | list_certificates, get_certificate_chain | ``````| Sign contract.pdf with our certificate and show the validation report. | chain → prepare → sign_hash → finish (branded stamp by default) | ``````| Sign contract.pdf with no visible stamp. | prepare --invisible-signature → sign_hash → finish | ``| Get a detached signature for the SHA-256 of release-manifest.json labelled “Release 2.1.0 manifest”. | sign_hash (format-agnostic) | ````````| My signing request is waiting for approval. Keep waiting and finish once approved. | Retry sign_hash with same approval_id + client_nonce, then finish | ## Troubleshooting | Symptom | Cause | Fix | ``| 401 Unauthorized | Missing or invalid OAuth session or API key | Reconnect the MCP URL (Connect) or re-issue lkag_…; use one auth mode only | | 403 Forbidden | Conflicting auth headers, or token missing agent connection claim | Single header only for API key path; reconnect OAuth for connector path | ``| denied | No matching allow rule or explicit deny | Fix policy; do not retry the same request | ````````| pending_approval after 120s | Approvers have not acted yet | Call sign_hash again with same approval_id and client_nonce | ````| Duplicate approvals | New client_nonce or new attempt after approval | Reuse the same nonce and approval_id to collect the signature; retries do not open a second approval | ``````| finish / validate failed | Trust anchor or stale state | Use correct chain PEM; do not re-run prepare after sign_hash; show full report | ````| preview_warnings | Malformed preview image | Fix PNG/JPEG and call sign_hash again on first attempt | [Plugin vs skill vs MCP](/docs/agents/concepts/) · [LK Approvals (PWA)](/docs/agents/approvals/) · [Console](/docs/console/) · [Security](/docs/security/) --- # Plugin vs skill vs MCP connector Source: https://www.liminalkeys.com/docs/agents/concepts/ Three pieces work together when Claude (or another agent host) signs with your company certificate. None of them receives your private key — signing happens in Liminal Keys custody over MCP using a **hash only**. ## MCP connector (remote account link) The connector is your live link to Liminal Keys. Production URL: ``` https://mcp.liminalkeys.com/mcp ``` In Claude, you add that URL and choose **Connect**. Sign-in uses **URL-only OAuth** with automatic client registration — you do not paste a client ID or client secret. You sign in with your **Liminal Keys account** (the same options as Console). The connector exposes four remote tools: `list_certificates`, `get_certificate_chain`, `sign_hash` (with optional human approval), and optional `timestamp`. Response envelopes are cryptographically signed; the skill verifies them. The private key never leaves Liminal Keys. ## Skill — liminalkeys-sign 0.1.10 (local instructions + program) A **skill** is agent instructions plus a small local program. The **liminalkeys-sign** skill tells the agent the exact steps and ships offline Python wheels and the `liminal-sign` helper. - **Hash locally** — for PDFs, `liminal-sign prepare` digests the file in the sandbox; only the 32-byte digest goes to MCP. - **Call** `sign_hash` on the connector (one approval on your phone or in LK Approvals when policy requires it). - **Finish locally** — `liminal-sign finish` embeds the signature, runs mandatory validation, and by default draws the branded visible stamp on the PDF. Standalone zip (same bits as the plugin bundle): [liminalkeys-sign-skill-0.1.10.zip](/downloads/liminalkeys-sign-skill-0.1.10.zip) ([SHA-256](/downloads/liminalkeys-sign-skill-0.1.10.zip.sha256)). ## Claude plugin — LiminalKeys/claude-plugin (install package) The **plugin** is the installable package that wires everything up for Claude Code and claude.ai: it registers the **liminalkeys-sign** skill and the MCP connector settings for `https://mcp.liminalkeys.com/mcp`. Install or refresh from the public **LiminalKeys/claude-plugin** marketplace — see [Claude setup](/docs/agents/#claude-setup) on the main AI agents guide. ## How they fit together Your PDF and chain PEM stay in the agent sandbox. Only digests and MCP messages cross the network. ``` ┌──────────────────────────── Claude (plugin installed) ────────────────────────────┐ │ │ │ SKILL (liminalkeys-sign) MCP CONNECTOR YOUR LK ACCOUNT │ │ ───────────────────── ─────────────── ───────────────── │ │ liminal-sign prepare ──hash──► sign_hash ────────────► Key Vault sign │ │ │ ▲ (private key │ │ │ previews │ never exported) │ │ ▼ │ approval (optional) │ │ liminal-sign finish ◄──signature────┘ │ │ embed + validate + stamp │ └───────────────────────────────────────────────────────────────────────────────────┘ ``` ## What to configure where | Piece | You configure | Runs where | ``| MCP connector | MCP URL + Connect (OAuth) or optional lkag_… API key header | Claude → Liminal Keys cloud | | Skill | Installed via plugin or skill zip upload | Agent sandbox (local CLI) | | Plugin | Marketplace add + install / refresh on claude.ai | Claude product | | Policy & approvals | Console → AI agents, policy rules, LK Approvals | Console + PWA | [AI agents & MCP setup](/docs/agents/) · [LK Approvals](/docs/agents/approvals/) · [Console](/docs/console/) --- # LK Approvals Source: https://www.liminalkeys.com/docs/agents/approvals/ When a policy rule uses **Require approval** for an AI agent, approvers decide in the **LK Approvals** web app — not in Console. Policy is still configured in Console; this app is the decision inbox only. ## URL and install Open [https://console.liminalkeys.com/approvals/](https://console.liminalkeys.com/approvals/) on a phone or desktop browser. - Sign in with your **Liminal Keys account** (same identity as Console) when you are listed as an approver on the rule. - Use the browser **Install** / **Add to Home Screen** action to install the PWA. - Allow web push notifications when prompted so new requests surface outside the app. - The installed app **refreshes sign-in in the background** while it is open and **re-registers web push** when you return to it, after a service worker update, or on a weekly cadence — so alerts and the session stay healthy without signing in again until your organization's refresh lifetime ends. ## Who can approve Only users listed as approvers on the applied **AI agent** policy rule receive requests. If you are not on the rule, the inbox stays empty. ## What approvers see - Agent-supplied **document label** - Up to three small **preview** images (agent-rendered, not verified against the digest) - Truncated **DigestHashHex** (full 64-character SHA-256 hash is stored server-side) Preview images may be PNG, JPEG, or WebP. The API does not receive the full document—only the digest—so page thumbnails must come from the agent (for example `pdftoppm`) or from a server metadata fallback when the agent sent only a blank grey placeholder. ## Timeout and MCP polling MCP `sign_hash` waits up to **120 seconds** by default (`poll_timeout_seconds`). If approvers have not acted, the tool returns `pending_approval` with an `approval_id`. The agent must call `sign_hash` again with the **same** `client_nonce` and that `approval_id` until the decision is signed or denied. [← AI agents & MCP](/docs/agents/) --- # Customer Azure Key Vault Source: https://www.liminalkeys.com/docs/security/customer-azure-key-vault/ # Bring your own Azure Key Vault Liminal Keys can sign with RSA keys that stay in **your** Azure Key Vault or Azure Managed HSM. Policy, approvals, and the sign audit remain on Liminal Keys; private keys are never sent to Liminal. ## Connect - Liminal Console → **Key providers** — **Connect Azure Key Vault** to register the vault URI and **Entra tenant ID** of the vault's organisation. - A customer Entra administrator opens the consent URL and assigns **Azure Key Vault Crypto User** (or a custom role with Sign, Verify, and Get on the signing key). - **Register key** with the full key URI (including version) and the leaf public certificate PEM. PKCS#12 import stays **hosted-only**. RS256 signing paths only in this release. [← Security overview](/docs/security/) ---