Get started with io.sign

io.sign is a system of containerised backend services that coordinates mobile or server-based signer devices to create key pairs and generate digital signatures. It combines a Threshold Signature Scheme (TSS) with Multi-Party Computation (MPC): TSS sets how much combined signing power is needed to produce a signature, while MPC lets the signers work together without revealing their private key shares or assembling the complete private key.

The signers also use MPC to generate a key pair together. The public key is available to your application, while the private key is held as separate shares across the signers. The complete private key is never assembled during key generation or signing. The exception is disaster recovery, where recovery material from backups can be combined to reconstruct the private key.

For a simple explanation of how TSS and MPC work together, with an example, see Digital signature algorithms.

How the system fits together

Your application sends requests to the io.sign backend, which coordinates approvals and the work performed by the signers. The signers hold the private key shares and carry out the cryptographic operations:

• A Mobile Signer runs on a user's mobile device and lets them review and approve requests.
• A Virtual Signer runs in your server infrastructure and evaluates requests against an approval policy.

You can use either signer type independently or combine them in the same vault. A vault brings together a public key, its signers, and the signing threshold. Each signer has a weight; the participating signers must have enough combined weight to meet that threshold. See Vaults, signers, and thresholds.

The basic flow is to connect your signers, create a vault to generate a key pair, and then submit requests to sign with that vault. io.sign returns the resulting signatures to your application. For blockchain transactions, your application, or io.vault Treasury, handles transaction construction and broadcast.

The steps below take you from choosing an environment to producing your first signature.

Choose your starting point

The v2.0 documentation version is separate from container and mobile app versions. Use compatible release versions supplied for your environment and pin container tags when deploying.

Prepare the environment

Before creating a vault or submitting a signing request, confirm that you have:

• Your organisation, user account, and permission to create vaults or submit requests.
• A valid licence that permits write operations.
• The API, signing-stream, authentication, and MQTT messaging endpoints for the same environment.
• Network and TLS access from each signer to the services it uses, including the identity provider.
• For a custom mobile environment, the full public configuration URL, such as https://sign.example.com/v2/app/config.

For self-hosting, configure backend environment variables before installing signers. Setting a public app configuration URL does not itself deploy authentication or an MQTT broker.

Register your signers

1. Install and register each Mobile Signer, or deploy and register each Virtual Signer.
2. Verify that the signers appear in the intended organisation using its management interface or API.
3. Protect each signer's backup and recovery material before assigning it signing power.
4. Choose signer weights and a vault threshold. Check which combinations of signers will be able to sign; see Vaults, signers, and thresholds.

For an evaluation that requires both a person and automation, use one Mobile Signer and one Virtual Signer, each with weight 1, and threshold 2. Neither can sign alone. Use test keys and requests with no real assets.

Create a test vault

Creating a vault starts key generation. The signers generate their shares together, and the completed vault provides the public key you will use to verify signatures.

1. In your environment's management interface or API, create a vault with the registered signer IDs, weights, threshold, and required signature algorithm.
2. Review the key-generation request on the Mobile Signer. For a Virtual Signer, ensure your policy explicitly permits the intended key-generation request.
3. Keep the required signers connected until key generation completes.
4. Confirm the vault reports completion and has a public key before submitting a signing request.
5. Export or sync updated recovery material. For a Virtual Signer, follow Virtual Signer disaster recovery.

Use the API specification served by your backend at /spec.json for the request and response shapes supported by your installed version. The public documentation also includes io.vault and io.network APIs; their transaction and custody endpoints are not interchangeable with the standalone io.sign API.

Complete your first signing request

With the vault ready, you can ask its signers to generate a signature for a test payload.

1. Submit a test signing request for the vault through your integration or environment's management interface.
2. On mobile, review the vault, operation, payload details, and warnings before approving. The Virtual Signer evaluates its policy independently.
3. Keep the participating signers reachable. An approval is a decision to participate; it is not a completed signature.
4. Wait for the request's final result through the API or webhooks.
5. Verify the returned signature against the vault public key and the exact payload using the chosen algorithm. See How io.sign signs transactions.

If you are signing a blockchain transaction, broadcast only after assembling and validating the chain-specific signed transaction. A completed io.sign request is not evidence of blockchain confirmation.

For complete native-transfer code, follow Sign and broadcast transactions for Bitcoin, EVM, Solana, and XRP using your own RPC endpoints.

Resolve common setup problems

Before assigning production signing power, test a rejected request, a policy outage, a signer restart, and recovery from a backup. See Testing the deployment.