Manual approval
Approve or reject Virtual Signer requests through a signed API call, at any time before they expire
Manual approval holds a Virtual Signer's key generation, resharing, and signing requests until your approver system approves or rejects them through an API on the Virtual Signer. Use it when a decision needs a person, a ticketing system, or a workflow that can't answer within a policy call.
Choose a mode
| Mode | Which requests wait for an approver | Configuration |
|---|---|---|
| Manual only | Every request the signer is asked to vote on. No policy server. | IOSIGN_SIGNER_BROKER_APPROVAL_MODE=manual-api |
| Hybrid | Requests your policy server answers with defer. approve, reject, and abstain work as before. | IOSIGN_SIGNER_BROKER_APPROVAL_MODE=api-approval and IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_ENABLED=true |
The Virtual Signer seals its approval mode when it first registers, so an existing signer can't move to manual-api. Hybrid keeps the api-approval mode, so you can turn it on for an existing signer. A policy server that answers defer to every request makes hybrid fully manual.
How a decision works
- The Virtual Signer receives a request and holds it as pending instead of voting. If you configure a webhook URL, it tells your system.
- Your approver system lists the pending requests and reads one. The request has the same shape your policy server receives, with a
content_digestthat identifies its content. - Your approver system signs the decision with an approver key and sends an approve or a reject.
- The Virtual Signer checks the signature and reads the request again from io.sign. It refuses the decision if the content changed. Otherwise it votes, and answers once the vote is submitted.
A request nobody decides expires in io.sign. The Virtual Signer sends no vote for it.
Before you begin
The API is post-quantum: every certificate and approver key uses ML-DSA (FIPS 204), and TLS uses a hybrid post-quantum key exchange. It accepts ML-DSA-65 and ML-DSA-87 keys.
Prepare:
- A TLS server certificate and private key for the API listener, with an ML-DSA key and the host name your approver system connects to. The certificate and any intermediates in its file must be signed with ML-DSA too.
- A certificate authority (CA) with an ML-DSA key that issues ML-DSA client certificates to your approver systems. The listener refuses any connection without a certificate from this CA.
- One or more ML-DSA approver key pairs. Keep the private keys in your approver system, ideally in a key store or hardware security module (HSM). The Virtual Signer only needs the public keys.
- A TLS client that supports TLS 1.3 with the hybrid key exchanges and ML-DSA certificates, such as OpenSSL 3.5 or later, or Go 1.27 or later.
These key stores can hold ML-DSA approver keys and sign decisions the way the Virtual Signer verifies them:
| Key store | Key | Signing |
|---|---|---|
| AWS KMS | ML_DSA_65 or ML_DSA_87 | ML_DSA_SHAKE_256, message type RAW |
| Google Cloud KMS | PQ_SIGN_ML_DSA_65 or PQ_SIGN_ML_DSA_87 | asymmetricSign with the message as data |
The API is signing authority. Anyone with a client certificate can list this signer's pending requests and read their content. Anyone who also holds an approver private key can approve them until they expire. Issue client certificates only to approver systems, restrict network access to the listener, and protect approver keys like the signer's own credentials.
Configure the Broker
Save each approver public key as a PEM PUBLIC KEY file named <key_id>.pem, for example treasury-ops.pem. The file name without .pem is the key ID your approver system sends with each decision. Put the files in one directory. The Broker refuses to start if the directory holds any other file; hidden files and subdirectories are ignored, so a Kubernetes Secret or ConfigMap mount works.
Then set:
# Manual only, for a new signer:
IOSIGN_SIGNER_BROKER_APPROVAL_MODE=manual-api
# Or hybrid, for a signer that uses a policy server:
# IOSIGN_SIGNER_BROKER_APPROVAL_MODE=api-approval
# IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_ENABLED=true
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_PORT=9443
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_TLS_CERT_FILE=/run/secrets/approvals-server.pem
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_TLS_KEY_FILE=/run/secrets/approvals-server-key.pem
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_CLIENT_CA_CERT_FILE=/run/secrets/approvals-client-ca.pem
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_APPROVER_KEYS_DIR=/run/secrets/approver-keysSee Environment variables for the optional settings: the decision freshness window, the decision timeout, the minimum time left for an approve, and the webhook URL.
The API listens on IOSIGN_SIGNER_BINDING_NETWORK_NAME and its own port, separate from the Broker's health and metrics listeners. It accepts TLS 1.3 only, with the key exchanges X25519MLKEM768, SecP256r1MLKEM768, and SecP384r1MLKEM1024, so a recorded session can't be decrypted later. It requires a client certificate. The Broker refuses to start if the server certificate, the client CA, or an approver key doesn't have an ML-DSA-65 or ML-DSA-87 key, or if the server certificate or an intermediate in its file isn't signed with ML-DSA-65 or ML-DSA-87, and the listener refuses a client certificate with another key type. The Broker reads the certificates and approver keys when it starts: restart it after you renew a certificate or change the keys.
At every start, the Broker logs a warning with the mode, the listener address, and the SHA-256 fingerprint of each approver key. Alert on fingerprints you don't expect.
Use the API
All paths are under https://<broker-host>:<port>/broker/approvals/v1. Errors are JSON: {"error": "<code>"}.
| Method and path | Result |
|---|---|
GET /requests | This signer's ID and its pending requests, soonest expiry first. |
GET /requests/{id} | One pending request with its full content. |
POST /requests/{id}/approve | Votes approve. |
POST /requests/{id}/reject | Votes reject. |
GET /requests returns:
{
"signer_id": "<SIGNER_ID>",
"requests": [
{
"id": "<REQUEST_ID>",
"type": "sign",
"vault_id": "<VAULT_ID>",
"expires_at": "2026-11-10T09:30:00Z",
"pending_since": "2026-11-09T09:31:12Z",
"content_digest": "<CONTENT_DIGEST>",
"deferral_reason": "Amount above the daily limit"
}
]
}type is keygen, reshare, or sign. deferral_reason appears in hybrid mode when your policy server returned a reason.
GET /requests/{id} returns the same fields, the signer ID, and request: the request in the shape your policy server receives as input, decoded transaction metadata included. See Sample approval requests. Review this response before you decide: the content_digest you sign must come from it.
Sign a decision
The approver signs these lines, joined with a line feed (\n) and with no trailing line feed:
io.finnet/vs/manual-approval-decision/v1
<signer_id>
<request_id>
<decision>
<content_digest>
<issued_at>
<nonce>
<key_id>| Line | Value |
|---|---|
signer_id | signer_id from GET /requests or GET /requests/{id}. It binds the decision to this signer. |
request_id | The request ID. |
decision | approve or reject. |
content_digest | content_digest from GET /requests/{id}, exactly as returned. Don't compute it yourself. |
issued_at | The current time in Unix seconds. |
nonce | 16 to 128 characters from A–Z, a–z, 0–9, _, and -. Use a new random nonce for every attempt, retries included. |
key_id | The approver key's file name without .pem. 1 to 64 characters from A–Z, a–z, 0–9, ., _, and -. |
Sign the message bytes with pure ML-DSA, not the pre-hash variant, and an empty context string. This is what the key stores above do by default.
Send the decision as the request body, with the signature in standard Base64 (4,412 characters for ML-DSA-65, 6,172 for ML-DSA-87):
{
"content_digest": "<CONTENT_DIGEST>",
"issued_at": 1794216672,
"nonce": "<NONCE>",
"key_id": "treasury-ops",
"signature": "<BASE64_SIGNATURE>"
}The body can also include reason, free text for your own records. The Virtual Signer doesn't store or log it.
The Virtual Signer accepts a decision for 300 seconds after issued_at, and up to 60 seconds before it to allow for clock skew. Change the 300 seconds with IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_DECISION_MAX_AGE. It accepts each nonce once per key. It keeps used nonces in memory, so after a restart it can accept the same signed decision again within those 300 seconds. A repeat can only cast the same decision on the same request and content.
Example in Go
This example reads a request, signs the decision with an ML-DSA key in a PKCS #8 PEM file, and sends it. It needs Go 1.27 or later and no other dependencies.
// Reads a pending request, signs the decision with an ML-DSA approver key, and sends it.
package main
import (
"bytes"
"crypto"
"crypto/mldsa"
"crypto/rand"
"crypto/tls"
"crypto/x509"
"encoding/base64"
"encoding/json"
"encoding/pem"
"fmt"
"io"
"log"
"net/http"
"os"
"strconv"
"strings"
"time"
)
func main() {
if len(os.Args) != 3 || (os.Args[2] != "approve" && os.Args[2] != "reject") {
log.Fatal("usage: decide <REQUEST_ID> approve|reject")
}
requestID, decision := os.Args[1], os.Args[2]
// https://<broker-host>:<port>/broker/approvals/v1
apiURL := os.Getenv("APPROVAL_API_URL")
client := newClient()
// The decision commits to the content returned here.
var pending struct {
SignerID string `json:"signer_id"`
ContentDigest string `json:"content_digest"`
}
status, body := call(client, http.MethodGet, apiURL+"/requests/"+requestID, nil)
if status != http.StatusOK {
log.Fatalf("GET /requests/%s: %d %s", requestID, status, body)
}
if err := json.Unmarshal(body, &pending); err != nil {
log.Fatal(err)
}
keyID := os.Getenv("APPROVER_KEY_ID")
issuedAt := time.Now().Unix()
nonce := make([]byte, 18)
if _, err := rand.Read(nonce); err != nil {
log.Fatal(err)
}
nonceText := base64.RawURLEncoding.EncodeToString(nonce)
message := strings.Join([]string{
"io.finnet/vs/manual-approval-decision/v1",
pending.SignerID, requestID, decision, pending.ContentDigest,
strconv.FormatInt(issuedAt, 10), nonceText, keyID,
}, "\n")
// Pure ML-DSA with the empty context. With a key in a cloud key store, send
// message to its signing call instead.
signature, err := approverKey().Sign(nil, []byte(message), crypto.Hash(0))
if err != nil {
log.Fatal(err)
}
payload, err := json.Marshal(map[string]any{
"content_digest": pending.ContentDigest,
"issued_at": issuedAt,
"nonce": nonceText,
"key_id": keyID,
"signature": base64.StdEncoding.EncodeToString(signature),
})
if err != nil {
log.Fatal(err)
}
status, body = call(client, http.MethodPost, apiURL+"/requests/"+requestID+"/"+decision, payload)
fmt.Println(status, string(body))
}
// newClient presents the approver system's client certificate. Go's defaults offer
// the post-quantum key exchange the listener requires.
func newClient() *http.Client {
caPEM, err := os.ReadFile(os.Getenv("APPROVAL_API_CA_FILE"))
if err != nil {
log.Fatal(err)
}
roots := x509.NewCertPool()
if !roots.AppendCertsFromPEM(caPEM) {
log.Fatal("no CA certificate found")
}
cert, err := tls.LoadX509KeyPair(os.Getenv("APPROVAL_CLIENT_CERT_FILE"), os.Getenv("APPROVAL_CLIENT_KEY_FILE"))
if err != nil {
log.Fatal(err)
}
return &http.Client{
Timeout: time.Minute,
Transport: &http.Transport{TLSClientConfig: &tls.Config{RootCAs: roots, Certificates: []tls.Certificate{cert}}},
}
}
func approverKey() *mldsa.PrivateKey {
raw, err := os.ReadFile(os.Getenv("APPROVER_PRIVATE_KEY_FILE"))
if err != nil {
log.Fatal(err)
}
block, _ := pem.Decode(raw)
if block == nil {
log.Fatal("no PEM block in the approver key file")
}
key, err := x509.ParsePKCS8PrivateKey(block.Bytes)
if err != nil {
log.Fatal(err)
}
mldsaKey, ok := key.(*mldsa.PrivateKey)
if !ok {
log.Fatal("the approver key is not ML-DSA")
}
return mldsaKey
}
func call(client *http.Client, method, url string, body []byte) (int, []byte) {
req, err := http.NewRequest(method, url, bytes.NewReader(body))
if err != nil {
log.Fatal(err)
}
req.Header.Set("Content-Type", "application/json")
resp, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
out, err := io.ReadAll(resp.Body)
if err != nil {
log.Fatal(err)
}
return resp.StatusCode, bytes.TrimSpace(out)
}Run it with the request ID and approve or reject:
go run . <REQUEST_ID> approveA successful decision returns:
{"id":"<REQUEST_ID>","decision":"approve","outcome":"voted"}Responses
| Status | error | Meaning and what to do |
|---|---|---|
| 200 | outcome is voted, or already_voted if this signer already cast the same decision. Repeating a decision is safe. | |
| 400 | bad_request | The body or a field is malformed. |
| 403 | forbidden | Unknown key ID, wrong signature, issued_at outside the accepted window, or a reused nonce. No vote. |
| 404 | not_found | The request isn't pending on this signer, or the path is unknown. |
| 405 | method_not_allowed | The path takes another method, listed in the Allow header. |
| 409 | content_changed | The request no longer matches content_digest. Read it again, review it, and sign again. No vote. |
| 409 | conflict | This signer already voted the other way. A decision can't be changed. |
| 410 | gone | The request expired, is no longer in voting, or has too little time left to be signed. No vote. |
| 429 | too_many_requests | Rate limited. Retry after the number of seconds in Retry-After. |
| 502 | read_failed | The Virtual Signer couldn't read the request from io.sign. Nothing was sent. Retry with a new nonce. |
| 502 | vote_failed | The Virtual Signer couldn't submit the vote. The request stays pending. Retry with a new nonce. |
| 503 | not_ready | The Virtual Signer isn't registered yet. |
| 504 | timeout | The read or decision took longer than the decision timeout, 30 seconds by default. After a decision, the vote may still have been submitted. Retry: you get already_voted if it was. |
Limits and behaviour
- Expiry. A request can wait until it expires in io.sign, 24 hours at most. The expiry also covers signing, so the Virtual Signer refuses an approve with
410when less than 300 seconds are left. A reject is accepted until expiry. You can change the 300 seconds withIOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_MIN_REMAINING. - Content changes. In hybrid mode, an approver can only approve what your policy server deferred. If the content changed since, reading the request returns
404, an approve returns409content_changed, and the request goes back to your policy server. It's pending again only if the policy defers it again. - Restarts. The Virtual Signer keeps pending requests in memory and lists them again from io.sign after a restart. In hybrid mode it asks your policy server again about requests it hasn't voted on, so keep your policy deterministic. A request this signer already voted on, by policy or by an approver, isn't sent to the policy again.
- Large queues. With more than 1,000 requests waiting for votes, a request that left voting can stay in
GET /requestsuntil it expires. Deciding it answers410. - Rate limits. Each client certificate can make 20 requests per second, with bursts of 40. Request bodies are limited to 16 KB.
- Webhooks. With
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_NOTIFICATION_URLset, the Virtual Signer sendsPOSTwith{"id", "type", "expires_at"}to that HTTPS URL when a request becomes pending. It uses the same TLS settings as your policy server. A webhook can be lost, so your approver system should also pollGET /requests.
Audit and monitoring
The Broker writes audit records whatever the configured log level:
- Every decision attempt, accepted or refused, with
event=manual_approval_decision, the client certificate's subject and SHA-256 fingerprint, the signer ID, key ID, request ID, decision, content digest,issued_at, nonce, and outcome. - Every read of a request with
GET /requests/{id}, withevent=manual_approval_read, the client certificate's subject and SHA-256 fingerprint, the request ID, the content digest returned, and the outcome.
Audit records never include reason or the policy server's deferral reason.
The Broker exposes these metrics on its Prometheus listener:
| Metric | Meaning |
|---|---|
vs_broker_manual_approval_pending{type} | Pending requests by type. |
vs_broker_manual_approval_decisions_total{outcome} | Decision attempts by outcome, such as voted, signature_refused, content_changed, and gone. |
vs_broker_manual_approval_pending_to_vote_seconds | Time from pending to vote. |
DeferralsViaAPI | Requests your policy server deferred. Without manual approval enabled, such a request is rejected and also counted in RejectionsViaAPI. |
Rotate keys and certificates
- Approver keys. Add the new ML-DSA public key file next to the old one and restart the Broker. Several keys can be active at once, so decisions signed with either key are accepted. Remove the old file and restart again when you no longer use it.
- Client certificates. The listener accepts any certificate the client CA issued, and it has no revocation list. To withdraw a client certificate, rotate the client CA. Short-lived client certificates limit the impact of a lost one.
- Server certificate. Replace the files and restart the Broker.
Updated 9 days ago