TKeeper logoTKeeperDevelopers
Download docs

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.

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

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"
  ]
}

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

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"
  ]
}

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",
    "authorityId": "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"
  ]
}