TKeeperDevelopers

OpenAPI

LLM index

The OpenAPI file is the source of truth:

It describes:

  • routes
  • request bodies
  • response bodies
  • error responses
  • authentication headers
  • permission templates
  • algorithm and scheme enums

If generated SDK helpers disagree with OpenAPI, treat OpenAPI as the current contract and update the SDK.

MCP

POST/mcpDiscover and call agent tools

Optional `mcp` feature. Supports `server/discover`, `tools/list`, and `tools/call` over HTTP POST with JSON-RPC 2.0. The host authenticates with the same Keeper token used by the public API. Tool discovery is permission filtered; calls check permission again. Requests with an `Origin` header are rejected.

Parameters

NameInTypeRequiredDescription
MCP-Protocol-Versionheaderenum(2026-07-28)Yes-
Mcp-Methodheaderenum(server/discover, tools/list, tools/call)YesMust match the JSON-RPC `method`.
Mcp-NameheaderstringNoRequired for `tools/call`; must match `params.name`.

Request Body

Required: Yes

application/json object

{
  "jsonrpc": "2.0",
  "id": "string",
  "method": "server/discover",
  "params": {
    "name": "string",
    "arguments": {},
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

Responses

200 JSON-RPC result, including tool errors and some protocol errors

application/json object | object

{
  "jsonrpc": "2.0",
  "id": null,
  "result": {
    "resultType": "complete",
    "_meta": {},
    "supportedVersions": [
      "string"
    ],
    "capabilities": {}
  }
}

400 Invalid JSON-RPC request, headers, or protocol version

application/json object

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 1,
    "message": "string",
    "data": {}
  }
}

403 Browser origin rejected

application/json object

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 1,
    "message": "string",
    "data": {}
  }
}

404 Unknown MCP method

application/json object

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 1,
    "message": "string",
    "data": {}
  }
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}

Audit

POST/v1/keeper/audit/verifyVerify one signed audit line

Request Body

Required: Yes

application/json object

{
  "event": {
    "id": "string",
    "peerId": 1,
    "integrityKeyVersion": 1,
    "timestamp": 1,
    "event": "string"
  },
  "signature": "string"
}

Responses

200 Verification result

application/json object

{
  "valid": true
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}
POST/v1/keeper/audit/verify/batchVerify a batch of signed audit lines

Request Body

Required: Yes

application/json object

{
  "logs": []
}

Responses

200 Verification results by event id

application/json object

{
  "key": {
    "valid": true
  }
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}

Inventory

GET/v1/keeper/compliance/inventoryList asset inventory

Parameters

NameInTypeRequiredDescription
logicalIdquerystringNo-
historicalquerybooleanNo-
lastSeenquerystringNo-
assetOwnerquerystringNo-
limitqueryinteger:int32No-

Responses

200 Asset inventory page

application/json object

{
  "inventory": {
    "generatedAt": 1,
    "peerId": 1,
    "threshold": 1,
    "totalPeers": 1,
    "items": [
      {
        "logicalId": "string",
        "status": "ACTIVE",
        "currentGeneration": 1,
        "authorities": [
          {
            "id": "string",
            "oci": "string"
          }
        ],
        "createdAt": 1,
        "updatedAt": 1
      }
    ]
  },
  "nextCursor": "string",
  "hasMore": true
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}

Consistency

POST/v1/keeper/consistency/fixTry to repair key consistency

Parameters

NameInTypeRequiredDescription
keyIdquerystringYes-

Responses

200 Consistency verdict

application/json object

{
  "verdict": "OK",
  "targetGeneration": 1,
  "versions": {
    "key": {
      "activeGen": 1,
      "pendingGen": 1
    }
  }
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}

ControlPlane

GET/v1/keeper/control/audit/sinksGet audit sink status

Responses

200 Audit sink status

application/json object

{
  "enabled": true,
  "sinks": [
    {
      "id": "string",
      "available": true
    }
  ]
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}
GET/v1/keeper/control/auth/configGet UI auth config

Responses

200 UI auth config

application/json object | object

{
  "id": "TOKEN",
  "header": "string"
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}
GET/v1/keeper/control/capabilitiesGet capabilities exposed by installed cryptographic platforms

Responses

200 Runtime control-plane capabilities

application/json object

{
  "algorithms": [
    "string"
  ]
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}
GET/v1/keeper/control/meGet authenticated subject

Responses

200 Authenticated subject

application/json object

{
  "subject": "string",
  "actor": "string",
  "permissions": [
    "string"
  ]
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}
GET/v1/keeper/control/systemGet cluster status for UI

Responses

200 Cluster status

application/json object

{
  "id": "string",
  "state": "READY",
  "threshold": 1,
  "totalPeers": 1,
  "peers": {
    "key": null
  }
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}

Keys

POST/v1/keeper/destroyDestroy one key generation

Destroys a historical key generation. Mono mode is local-only and allows any non-current generation. Threshold mode coordinates across peers and requires the generation to be at least two generations behind the active one.

Request Body

Required: Yes

application/json object

{
  "keyId": "string",
  "generation": {},
  "approvals": {
    "keeperId": 0,
    "nonce": "",
    "timestamp": 1,
    "proofs": []
  }
}

Responses

204 Generation destroyed

- -

299 Threshold destroy committed by quorum, but not all peers

- -

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}
GET/v1/keeper/publicKeyGet public key

Read-only key operation that remains available in recovery mode for generation comparison.

Parameters

NameInTypeRequiredDescription
keyIdquerystringYes-
generationqueryinteger:int32No-
tweakquerystringNo-

Responses

200 Public key

application/json object

{
  "data64": "string"
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}

ECIES

POST/v1/keeper/ecies/decryptDecrypt ECIES ciphertext

Decrypts in the current quorum mode. Mono mode decrypts locally. Threshold mode collects peer partial decrypts and verifies DLEQ proofs.

Request Body

Required: Yes

application/json object

{
  "keyId": "string",
  "algorithm": "AES_GCM",
  "generation": {},
  "ciphertext64": "string"
}

Responses

200 Plaintext

application/json object

{
  "plaintext64": "string",
  "imposters": [
    "string"
  ]
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}
POST/v1/keeper/ecies/encryptEncrypt with ECIES public key

Encryption uses the public key and does not require peer participation.

Request Body

Required: Yes

application/json object

{
  "keyId": "string",
  "algorithm": "AES_GCM",
  "plaintext64": "string",
  "tweak": {}
}

Responses

200 Ciphertext

application/json object

{
  "ciphertext64": "string",
  "generation": 1
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}

DryRun

POST/v1/keeper/emulateEvaluate an authority command without executing it

Requires the optional `dry-run` feature. Resolves the key authority and evaluates its policy without signing, consuming approvals, or mutating key state. `ALLOW_WITH_REQUIREMENTS` includes every four-eye approval requirement needed by the authority policy.

Request Body

Required: Yes

application/json object

{
  "keyId": "string",
  "command": {
    "type": "string",
    "authorityId": "string",
    "artifact": {
      "scheme": "string",
      "hash": "NONE",
      "data64": "string"
    }
  }
}

Responses

200 Authority policy evaluation

application/json object

{
  "decision": "ALLOW",
  "matches": [
    {
      "id": "string",
      "effect": "ALLOW"
    }
  ],
  "approvalRequirements": [
    {
      "policyId": "string",
      "source": "string",
      "threshold": 1,
      "approvers": {
        "key": {
          "algorithm": "string",
          "publicKey64": "string",
          "metadata": {
            "key": "string"
          }
        }
      }
    }
  ]
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}

Expiration

GET/v1/keeper/expiresList expiring key policy entries

Supply either a positive `windowSec`, or `to` with optional `from`. `windowSec` cannot be combined with `from` or `to`, and `from` cannot exceed `to`.

Parameters

NameInTypeRequiredDescription
typequeryenum(apply, process)Yes-
limitqueryinteger:int32No-
cursorquerystringNo-
windowSecqueryinteger:int64No-
fromqueryinteger:int64No-
toqueryinteger:int64No-

Responses

200 Expiration page

application/json object

{
  "items": [
    {
      "type": "APPLY",
      "logicalId": "string",
      "generation": 1,
      "expiresAt": 1
    }
  ],
  "next": "string"
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}
GET/v1/keeper/expires/applyList keys with apply policy expiring in a window

Parameters

NameInTypeRequiredDescription
limitqueryinteger:int32No-
cursorquerystringNo-
windowSecqueryinteger:int64Yes-

Responses

200 Expiration page

application/json object

{
  "items": [
    {
      "type": "APPLY",
      "logicalId": "string",
      "generation": 1,
      "expiresAt": 1
    }
  ],
  "next": "string"
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}
GET/v1/keeper/expires/expiredList expired key policy entries

Parameters

NameInTypeRequiredDescription
typequeryenum(apply, process)Yes-
limitqueryinteger:int32No-
cursorquerystringNo-

Responses

200 Expiration page

application/json object

{
  "items": [
    {
      "type": "APPLY",
      "logicalId": "string",
      "generation": 1,
      "expiresAt": 1
    }
  ],
  "next": "string"
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}
GET/v1/keeper/expires/processList keys with process policy expiring in a window

Parameters

NameInTypeRequiredDescription
limitqueryinteger:int32No-
cursorquerystringNo-
windowSecqueryinteger:int64Yes-

Responses

200 Expiration page

application/json object

{
  "items": [
    {
      "type": "APPLY",
      "logicalId": "string",
      "generation": 1,
      "expiresAt": 1
    }
  ],
  "next": "string"
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}

Integrity

POST/v1/keeper/integrity/rotateRotate audit integrity key

Rotates this peer's audit and internal-response integrity key. Restart every peer after rotation so process-local peer key pins are re-enrolled.

Responses

204 Integrity key rotated

- -

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}

System

GET/v1/keeper/peerIdGet local peer id

Responses

200 Peer id

application/json object

{
  "serviceId": 1,
  "result": 1
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}
GET/v1/keeper/pingLightweight readiness status

Responses

200 Readiness flag

application/json object

{
  "ready": true,
  "peerId": 1,
  "threshold": 1,
  "total": 1
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}
GET/v1/keeper/system/healthLiveness probe

Responses

204 Service is up

- -

POST/v1/keeper/system/initInitialize keeper

Writes keeper identity and quorum settings into the sealed store. `threshold=1,total=1` initializes mono mode. `threshold>1` initializes threshold/MPC mode.

Request Body

Required: Yes

application/json object

{
  "peerId": 1,
  "threshold": 1,
  "total": 1
}

Responses

200 Provider initialization data

application/json object

{
  "threshold": 1,
  "total": 1,
  "shares64": [
    "string"
  ]
}

204 Initialized without provider payload

- -

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}
GET/v1/keeper/system/readyReadiness probe

Responses

204 Keeper is unsealed

- -

503 Keeper is not ready

- -

POST/v1/keeper/system/sealSeal keeper

Responses

204 Keeper sealed

- -

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}
GET/v1/keeper/system/statusGet keeper status

Responses

200 Keeper status

application/json object

{
  "sealedBy": "string",
  "state": "UNINITIALIZED",
  "progress": {
    "ready": true
  }
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}
GET/v1/keeper/system/unsealUnseal with the configured automatic seal provider

Responses

200 Unseal progress

application/json object | object

{
  "ready": true
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}
POST/v1/keeper/system/unsealSubmit unseal shares

Request Body

Required: Yes

application/json object | object

Responses

200 Unseal progress

application/json object | object

{
  "ready": true
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}

Recovery

POST/v1/keeper/recovery/recoverRebuild key-scoped state on this peer

Call this endpoint on the damaged keeper. The keeper asks exactly `threshold` remote helpers for the key description, requires them to agree on the algorithm and current generation, and selects the matching recovery flow locally. Available only when the artifact includes the corresponding recovery feature and every participating keeper runs with `keeper.recovery=true`. Supports any configured quorum with `1 < threshold < total`. All non-destroyed generations must belong to one crypto platform; mixed ECC/PQC rotation history fails closed without installing a partial recovery. After all operator-selected helpers agree, the target discards and atomically rebuilds the logical key's shares, metadata, policies, destroy state, public side-state, and derived indexes.

Request Body

Required: Yes

application/json object

{
  "keyId": "string",
  "helperIds": [
    1
  ]
}

Responses

200 All non-destroyed generations are present and verified on the target peer

application/json object

{
  "keyId": "string",
  "algorithm": "string",
  "targetPeerId": 1,
  "currentGeneration": 1,
  "recoveredGenerations": [
    null
  ],
  "helpers": [
    1
  ]
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}

Composition

POST/v2/keeper/composeSign and compose an artifact

Uses the same request, permission, authority, policy, approval, and signing checks as `/v2/keeper/sign`. EVM, TRON, XRP, and Solana commands return signed transactions. AP2 and MC Intent commands return payment credentials. Types without a composer, including Bitcoin and X.509, return `CalculatedSignature`. Composition does not broadcast or submit the result.

Request Body

Required: Yes

application/json object

{
  "keyId": "string",
  "command": {
    "type": "string",
    "authorityId": "string",
    "artifact": {
      "scheme": "string",
      "hash": "NONE",
      "data64": "string"
    }
  },
  "tweak": {},
  "approvals": {
    "keeperId": 0,
    "nonce": "",
    "timestamp": 1,
    "proofs": []
  }
}

Responses

200 Composed artifact or raw signature fallback

application/json object | object | object | object

{
  "type": "evm.transaction",
  "rawTransaction": "string",
  "transactionHash": "string",
  "generation": 1,
  "imposters": [
    "string"
  ]
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}

DKG

POST/v2/keeper/dkgCreate, rotate, or refresh a key generation

Runs the key lifecycle operation in the current quorum mode. Mono mode manages full key material locally. Threshold mode runs distributed key generation across peers.

Request Body

Required: Yes

application/json object

{
  "keyId": "string",
  "algorithm": "string",
  "authorities": [
    {
      "id": "string",
      "oci": "string"
    }
  ],
  "mode": "CREATE"
}

Responses

204 Lifecycle operation completed

- -

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}

Quorum

POST/v2/keeper/quorum/promotePromote mono keeper into threshold quorum

Promotes a mono keeper into a threshold quorum. Target peers must already be initialized, unsealed, and configured with the requested threshold and total. The promoted keeper becomes peer 1 and must be restarted before normal operations continue.

Request Body

Required: Yes

application/json object

{
  "threshold": 1,
  "total": 1
}

Responses

200 Promotion completed; restart the keeper before normal operations

application/json object

{
  "peerId": 1,
  "threshold": 1,
  "total": 1,
  "promotedKeys": 1,
  "restartRequired": true
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}

Signing

POST/v2/keeper/signSign in the current quorum mode

Materializes the command, evaluates key controls, and signs using the current quorum mode. Mono mode signs locally. Threshold mode uses FROST or GG20.

Request Body

Required: Yes

application/json object

{
  "keyId": "string",
  "command": {
    "type": "string",
    "authorityId": "string",
    "artifact": {
      "scheme": "string",
      "hash": "NONE",
      "data64": "string"
    }
  },
  "tweak": {},
  "approvals": {
    "keeperId": 0,
    "nonce": "",
    "timestamp": 1,
    "proofs": []
  }
}

Responses

200 Signature result

application/json object

{
  "type": "string",
  "signature64": {},
  "generation": 1,
  "imposters": [
    "string"
  ]
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}
POST/v2/keeper/sign/verifyVerify signature

Request Body

Required: Yes

application/json object

{
  "keyId": "string",
  "generation": {},
  "command": {
    "type": "string",
    "artifact": {
      "scheme": "string",
      "hash": "NONE",
      "data64": "string"
    }
  },
  "signature64": "string"
}

Responses

200 Verification result

application/json object

{
  "valid": true
}

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}

TrustedDealer

POST/v2/keeper/storage/storeImport key material through trusted dealer flow

Imports existing private key material into the current quorum mode. Mono mode stores the key locally. Threshold mode splits the key into peer shares and stores commitments.

Request Body

Required: Yes

application/json object

{
  "keyId": "string",
  "algorithm": "string",
  "authorities": [
    {
      "id": "string",
      "oci": "string"
    }
  ],
  "value64": {}
}

Responses

200 Key material stored

- -

default Error response

application/json object

{
  "error": "KEEPER_ALREADY_INITIALIZED",
  "details": "string",
  "imposters": [
    "string"
  ],
  "dead": [
    "string"
  ]
}