System-signed intent configuration

Use this page to understand the configuration and governance steps that support API-only system-signed intent submission. The examples show possible deployment shapes; key storage, certificate handling, service-caller identity, policy design, and rollout sequencing depend on your environment.

System-signed intents let an API service caller submit selected proposal types without sending a client-side payload signature. The platform signs the proposal internally, and policy evaluation admits it only when a matching policy uses intentOrigin: "SystemSigned".

Current release packages enable the system-signed intent configuration by default at deployment level. This makes Gateway and Notary capable of processing the flow, but it does not activate system-signed traffic by itself.

System-signed intents remain disabled until Notary is activated through governed state:

• The Gateway system signing public key is registered with purpose: "SystemSignatures".
• NOTARY_SYSTEM_SIGNED_INTENTS_ENABLED is set to enabled: true.
• At least one policy with intentOrigin: "SystemSigned" matches the proposal.

System-signed intents are useful for service-to-service automation where a trusted platform service needs to propose a narrow set of repeatable intents, but you do not want that service to hold or manage a user signing key.

Use cases that fit this model include:

The documented product use cases in this release are Omnibus automation and Gas Station fee funding. Gas Station previously used a dedicated bot user for funding transactions; it now submits funding as system-signed intents, so it requires the same activation and policy setup as Omnibus. User-triggered Omnibus flows, such as omnibus creation and withdrawals, still return unsigned Custody intents for the client to sign and submit through the normal user-signed intent flow.

System-signed intents are not a shortcut around governance. Use them only where the service caller, intent type, target domain, and policy conditions can be tightly scoped. Keep policy creation, broad administrative changes, and user-initiated business decisions on the normal user-signed path unless your governance process explicitly approves a different model.

Location: silo.gateway.system-signed-intents

There is no Gateway key-material-path setting for system-signed intents. Gateway does not load a pre-provisioned wrapped signing key from a mounted file. It mints and stores the signing key automatically, as described in Automatic key provisioning.

The signing component is a dedicated KMS Connect instance for Gateway, commonly configured with platform: kms_soft. Do not reuse the Notary KMS Connect instance for system-signed intents. The system signing key must remain separate from Notary collection-signing, messaging, and user API signing keys.

The chart values for this feature may group the related Gateway and signing-component settings under a systemSignedIntents section.

This example shows the shape of a sidecar-style deployment. Use the exact values and secret names from your release package and secret-management process.

systemSignedIntents:
  enabled: true
  sidecar:
    enabled: true
  platform: kms_soft
  kms_soft:
    existingSecret:
      name: gateway-system-signing-master
      key: master
  kmsConnect:
    hostname: 127.0.0.1
    port: 10000
    usePlaintext: true

This configuration wires Gateway to the dedicated signing component. It does not register the Gateway public key in Notary, enable the runtime system property, or create policies.

Gateway provisions the system signing keypair automatically on first boot.

1. Gateway queries operations.gateway_system_signing_key for an active key row.
2. If an active row exists, Gateway loads the wrapped key and public key metadata.
3. If no active row exists, Gateway asks the dedicated KMS Connect instance to generate an Ed25519 keypair.
4. Gateway stores the wrapped private key, public key, creation time, and active flag in operations.gateway_system_signing_key.
5. On each system-signed proposal, Gateway sends the wrapped key to the dedicated signing component for signing. Gateway does not hold the unwrapped private key.

The dedicated KMS Connect instance does not persist the Gateway signing key. It holds the master wrapping key used to wrap and unwrap the Gateway signing key during generation and signing. The wrapped signing key lives in the Gateway database.

The Gateway-minted public key is not automatically trusted by Notary. Notary trusts only the key referenced by the governed NOTARY_SYSTEM_SIGNING_KEY system property. Register the Gateway public key before sending system-signed traffic. Gateway refuses to sign until its key matches the registered NOTARY_SYSTEM_SIGNING_KEY.

Call GET /v1/system-signing/info to retrieve the public key that Gateway minted:

curl -X GET "${CUSTODY_API_URL}/v1/system-signing/info" \
  -H "Authorization: Bearer ${JWT_TOKEN}"

The response lists the Gateway signing keys, newest first. The active key is the key with active: true.

{
  "signingKeys": [
    {
      "publicKey": "MCowBQYDK2VwAyEA...",
      "createdAt": "2026-06-26T12:00:00.000Z",
      "active": true
    }
  ]
}

The endpoint returns only public key material and bookkeeping fields. It never returns the wrapped private key.

This endpoint is for inspection and registration. It does not regenerate or rotate Gateway signing keys.

After the deployment can sign system-signed proposals, governance must allow Notary to verify and process them.

1. Retrieve the active Gateway public key with GET /v1/system-signing/info.
2. Register the key during Genesis, or after launch with v0_RegisterTrustedPublicKey and purpose: "SystemSignatures".
3. Enable the runtime property NOTARY_SYSTEM_SIGNED_INTENTS_ENABLED.
4. Create policies with intentOrigin: "SystemSigned" for the specific intent types and service callers you want to allow.
5. Submit system-signed proposal bodies with request.type: "SystemSigned".

For post-genesis registration, submit a user-signed intent with a payload similar to the following:

"payload": {
  "publicKey": "MCowBQYDK2VwAyEA...",
  "purpose": "SystemSignatures",
  "type": "v0_RegisterTrustedPublicKey"
}

When this intent executes, Notary adds the public key to the trusted public key collection and sets NOTARY_SYSTEM_SIGNING_KEY to that key. The legacy v0_AddTrustedPublicKeysForMigration intent is not a registration path for SystemSignatures keys.

After the signing key is registered, submit a user-signed v0_SetSystemProperty intent with a payload similar to the following:

"payload": {
  "value": {
    "type": "NotarySystemSignedIntentsEnabledProperty",
    "value": {
      "enabled": true
    }
  },
  "type": "v0_SetSystemProperty"
}

If the deployment configuration is present but this property is absent or set to false, system-signed proposals remain disabled.

System-signed intents let an API service caller submit proposals with a JWT and no client-side user signature. Keep the controls narrow:

• Scope each SystemSigned policy to the smallest required set of intentTypes.
• Check both context.submitter.custodyRoles and context.submitter.subject in policy conditions, so a role alone is not enough to match the policy.
• Use approval workflows for high-risk intent types. Omit workflow only when automatic execution has been assessed and approved.
• Govern identity provider role assignments for service callers with the same change control you apply to custody policies.
• Keep the Gateway signing component separate from Notary KMS Connect.
• Monitor signature verification failures and unusual request rates per service caller.
• For incident response, disable NOTARY_SYSTEM_SIGNED_INTENTS_ENABLED, lock or tighten the matching SystemSigned policies, or disable the service account at the identity provider.

• Intent request structure
• Manage intents and approvals
• Policies
• Policy reference
• Authenticate API requests