Key Management

There are several kinds of key on XKOVA, and they are deliberately separated. Member wallet keys move value and remain non-exportable in the configured MPC provider, or remain with an external owner. Treasury Safe moves require the configured owner quorum. The XKOVA Relayer submits accepted signatures and pays gas. API keys provide bearer authorization. A separate customer-held asymmetric key proves possession for production mutations.

The kinds of key

Key	Held by	What it can do
Thirdweb MPC human-wallet key material	Non-exportable in Thirdweb's MPC infrastructure.	Produces member or staff signatures after a custom-JWT provider session is established.
External EOA key	The external owner.	Produces signatures independently of XKOVA.
Treasury Safe owner keys	Each owner wallet under its own custody and session model.	Each signs a Safe transaction; the configured N of M quorum is needed to move treasury funds.
Thirdweb custom-JWT signing key	XKOVA's protected issuer.	Bootstraps a general Thirdweb provider signing session for one canonical human-wallet subject. It is signing-critical authority.
Integrator API key	The integrator, on a server.	Bearer authorization for customer API calls scoped to one workspace.
Request-signing key	The integrator's KMS, HSM, or key provider.	Proof of possession for production mutations. It grants no authority without the bound bearer API key.

Human-wallet key material stays non-exportable

Thirdweb's MPC service keeps human-wallet private-key material non-exportable. XKOVA receives the public address and returned signatures, not the private-key material. Externally controlled EOAs keep their private keys with the external owner. A Safe holds value at the contract and enforces signatures from its configured owner quorum. See the Non-custodial Model and Wallet Providers.

MPC key non-exportability does not remove signing-session authority. XKOVA's custom-JWT issuer plus the public Thirdweb client can establish a general provider session for the named wallet. Protect the issuer like signing authority. Thirdweb does not enforce the XKOVA business purpose on that session.

Relayer authority is separate from wallet-signing authority

The XKOVA Relayer is the on-chain sender and pays gas, but the contract still requires a valid configured owner signature or Safe quorum. Compromising only the relayer does not provide those signatures. The broader platform threat model also includes the custom-JWT issuer used for Thirdweb MPC wallets. XKOVA limits that path with owner-specific authorization, a frozen payload, exact signature acceptance, short-lived memory-only browser ceremonies, and on-chain verification. See the Security Model.

API keys: issued once, then rotated

Shown once. A new API key's secret is returned only at creation, and a rotated key's replacement secret is returned only by the rotate call, matching the create-time behavior. Only a prefix (visible in the console) and a hash are stored, so the full secret is never shown again or logged. On a fresh workspace the first creation is governance held pending owner attestation; the approved re-submission is the call that returns the secret. See Policies and Quorum Governance.
Test versus live. Test keys are valid only against the sandbox; live keys are valid only against production after production access is approved.
Rotation. Rotating a key returns a single replacement, and the old secret stops verifying immediately; there is no grace window for API keys (webhook signing secrets keep one, API keys do not). Rotation is a step up action, so it requires a fresh authentication proof.
Revocation. Revoking a key makes it invalid on the next verification. Deleting a key is a cleanup step that only works after it has been revoked.
Scoped grants. A key carries roles, and additional role grants can be attached or revoked without rotating the secret, with a cascade on revoke. See Authentication.

Production request-signing credentials

A production customer mutation requires two distinct credentials: the workspace API key as bearer authorization and an active asymmetric signing credential bound to the same API principal. The SDK sends Signature-Input and Signature using XKOVA's strict RFC 9421 profile, plus the RFC 9530 Content-Digest field when a body is present. Production reads remain bearer-only. Sandbox mutations may use the same signing profile when configured, but do not require it.

The customer keeps the private key in its own KMS, HSM, or key provider. The SDK supports async signing callbacks for P-256 P1363, Ed25519, and RSA-PSS with SHA-256, MGF1 SHA-256, and a 32-byte salt, and never receives exportable private-key material. XKOVA pins the algorithm to the credential resolved by keyid and omits the RFC 9421 alg parameter, because RFC 9421 does not register an rsa-pss-sha256 value. Signing-credential registration, rotation, revocation, and public-key updates are private management actions, not methods in the customer @xkova/sdk package. See the SDK Overview for the transport profile.

Rotation registers one successor and requires proof of possession before activation. Only one live successor may reference a predecessor. Activating the successor starts a bounded five-minute overlap so the customer can switch signers without widening signature freshness. Either credential can still be revoked immediately.

Webhook signing secrets

Each webhook endpoint has a signing secret used to sign deliveries. Rotating it issues a new secret while a grace window keeps the old one valid, so you can verify with both during the cutover and switch over without dropping events. Secret rotation is a step up action. See Webhooks.

Secrets are not exposed

Human MPC private-key material is never exposed to XKOVA or to integrators.
The 60-second Thirdweb custom JWT is a transient signing-session bootstrap, not private-key material. It remains memory-only in the controlled signing page and is disposed immediately after the ceremony.
API key secrets are shown once and never returned again; only a prefix and a hash persist.
Request-signing private keys stay in the customer's KMS, HSM, or key provider; XKOVA stores only the registered public key and credential metadata.
The Authorization header is redacted from logs; mirror that practice in your own code.
Rotate immediately if any secret is exposed, using the rotate and reissue flow.

Never commit API keys to source and never log the Authorization header. Keep tenant keys on a server or trusted worker, not in a browser.

See Authentication for key formats, rotation, and the step up flow, Wallet Providers for how member wallets are provisioned, and the Security Model for how these keys fit the threat model.

Was this helpful?