Keymaster API

warning

This feature is currently in the experimental stage of development. Do not use it in production environments or presume it is secure. Expect breaking changes.

• General
  • getCheck if the API is ready
  • getList all registries
  • postCreate an asset
• Wallet
  • getLoad wallet
  • putSave wallet
  • postCreate a new wallet
  • postBackup wallet
  • postRecover wallet
  • postCheck wallet
  • postFix wallet
  • getGet decrypted mnemonic
  • postRotate keys
  • postEncrypt a message
  • postDecrypt a message
  • postEncrypt JSON
  • postDecrypt JSON
  • postAdd a signature
  • postVerify a signature
• Identity
  • getGet current ID
  • putSet current ID
  • getList all IDs
  • postCreate a new ID
  • getResolve an ID
  • delRemove an ID
  • postBackup an ID
  • postRecover an DID
• Name
  • getList all names
  • postAdd a new name
  • getResolve a name to DID
  • delRemove a name
• Challenge
  • getCreate an empty challenge
  • postCreate a custom challenge
  • postCreate a response to a challenge
  • postVerify a response
• Group
  • postCreate a new group
  • getGet a group
  • postAdd a member to a group
  • postRemove a member from a group
  • postTest if a member is in a group
• Credential
  • postBind a credential
  • getList all held credentials
  • postAccept a credential
  • getGet a credential
  • delRemove a credential
  • postPublish a credential
  • postUnpublish a credential
  • getList all issued credentials
  • postIssue a credential
  • getGet an issued credential
  • postUpdate an issued credential
  • delRevoke an issued credential
• Poll
  • postCreate a poll
  • getView a poll
  • postVote in a poll
  • putUpdate a poll
  • postPublish a poll
  • delUnpublish a poll
• Schemas
  • postCreate a template
  • postCreate new schema
  • getList schemas
  • getGet a schema
  • putUpdate a schema
  • postTest if id is a valid schema

API docs by Redocly

Keymaster API (1.0.0)

Download OpenAPI specification:Download

API for managing wallets, identities, credentials, and more

General

General API routes

Check if the API is ready

Responses

https://keychain.org/ready

Response samples

• 200

Content type

application/json

{

• "ready": true

}

List all registries

Responses

https://keychain.org/registries

Response samples

• 200

Content type

application/json

{

• "registries": [

  • "local",
  • "hyperswarm",
  • "TBTC"

  ]

}

Create an asset

Request Body schema: application/json

required

asset

object

Responses

https://keychain.org/assets/

Request samples

• Payload

Content type

application/json

{

• "asset": { }

}

Response samples

• 200

Content type

application/json

{

• "did": "did:test:z3v8Auaha4rszsBwMyApaY9eUR1pipjGASYvqqfuXiXhxA8DXmo"

}

Wallet

Wallet management routes

Load wallet

Responses

https://keychain.org/wallet

Response samples

• 200

Content type

application/json

{

• "seed": {

  • "mnemonic": "string",
  • "hdkey": {

    • "xpriv": "string",
    • "xpub": "string"

    }

  },
• "counter": 2,
• "ids": {

  • "example-id": {

    • "did": "did:test:string",
    • "account": 1,
    • "index": 0

    }

  },
• "names": {

  • "example-name-1": "did:string",
  • "example-name-2": "did:string",
  • "example-name-3": "did:string"

  },
• "current": "example-id"

}

Save wallet

Request Body schema: application/json

required

wallet

object

Responses

https://keychain.org/wallet

Request samples

• Payload

Content type

application/json

{

• "wallet": { }

}

Response samples

• 200

Content type

application/json

{

• "ok": true

}

Create a new wallet

Request Body schema: application/json

required

mnemonic	string
overwrite	boolean

Responses

https://keychain.org/wallet/new

Request samples

• Payload

Content type

application/json

{

• "mnemonic": "string",
• "overwrite": true

}

Response samples

• 200

Content type

application/json

{ }

Backup wallet

Responses

https://keychain.org/wallet/backup

Response samples

• 200

Content type

application/json

{

• "ok": true

}

Recover wallet

Responses

https://keychain.org/wallet/recover

Response samples

• 200

Content type

application/json

{ }

Check wallet

Responses

https://keychain.org/wallet/check

Response samples

• 200

Content type

application/json

{ }

Fix wallet

Responses

https://keychain.org/wallet/fix

Response samples

• 200

Content type

application/json

{ }

Get decrypted mnemonic

Responses

https://keychain.org/wallet/mnemonic

Response samples

• 200

Content type

application/json

"equip vital solution badge crucial pitch excite fork favorite soldier scene tray"

Rotate keys

Responses

https://keychain.org/keys/rotate

Response samples

• 200

Content type

application/json

{

• "ok": true

}

Encrypt a message

Request Body schema: application/json

required

msg	string
receiver	string
options	object

Responses

https://keychain.org/keys/encrypt/message

Request samples

• Payload

Content type

application/json

{

• "msg": "string",
• "receiver": "string",
• "options": { }

}

Response samples

• 200

Content type

application/json

{

• "did": "did:test:z3v8Auaha4rszsBwMyApaY9eUR1pipjGASYvqqfuXiXhxA8DXmo"

}

Decrypt a message

Request Body schema: application/json

required

did

string

Responses

https://keychain.org/keys/decrypt/message

Request samples

• Payload

Content type

application/json

{

• "did": "string"

}

Response samples

• 200

Content type

application/json

"string"

Encrypt JSON

Request Body schema: application/json

required

json	object
receiver	string
options	object

Responses

https://keychain.org/keys/encrypt/json

Request samples

• Payload

Content type

application/json

{

• "json": { },
• "receiver": "string",
• "options": { }

}

Response samples

• 200

Content type

application/json

{

• "did": "did:test:z3v8Auaha4rszsBwMyApaY9eUR1pipjGASYvqqfuXiXhxA8DXmo"

}

Decrypt JSON

Request Body schema: application/json

required

did

string

Responses

https://keychain.org/keys/decrypt/json

Request samples

• Payload

Content type

application/json

{

• "did": "string"

}

Response samples

• 200

Content type

application/json

{ }

Add a signature

Request Body schema: application/json

required

contents

string

Responses

https://keychain.org/keys/sign

Request samples

• Payload

Content type

application/json

{

• "contents": "string"

}

Response samples

• 200

Content type

application/json

{ }

Verify a signature

Request Body schema: application/json

required

json

object

Responses

https://keychain.org/keys/verify

Request samples

• Payload

Content type

application/json

{

• "json": { }

}

Response samples

• 200

Content type

application/json

true

Identity

Identity management routes

Get current ID

Responses

https://keychain.org/ids/current

Response samples

• 200

Content type

application/json

"string"

Set current ID

Request Body schema: application/json

required

name

string

Responses

https://keychain.org/ids/current

Request samples

• Payload

Content type

application/json

{

• "name": "string"

}

Response samples

• 200

Content type

application/json

{

• "ok": true

}

List all IDs

Responses

https://keychain.org/ids

Response samples

• 200

Content type

application/json

{

• "ids": [

  • "Alice",
  • "Bob",
  • "Carol"

  ]

}

Create a new ID

Request Body schema: application/json

required

name	string
options	object

Responses

https://keychain.org/ids

Request samples

• Payload

Content type

application/json

{

• "name": "string",
• "options": { }

}

Response samples

• 200

Content type

application/json

{

• "did": "did:test:z3v8Auaha4rszsBwMyApaY9eUR1pipjGASYvqqfuXiXhxA8DXmo"

}

Resolve an ID

path Parameters

id required

string

Responses

https://keychain.org/ids/{id}

Response samples

• 200

Content type

application/json

{

• "@context": "https://w3id.org/did-resolution/v1",
• "didDocument": {

  • "@context": [

    • "https://www.w3.org/ns/did/v1"

    ],
  • "id": "did:test:string",
  • "verificationMethod": [

    • {

      • "id": "#key-1",
      • "controller": "did:test:string",
      • "type": "string",
      • "publicKeyJwk": {

        • "kty": "EC",
        • "crv": "secp256k1",
        • "x": "string",
        • "y": "string"

        }

      }

    ],
  • "authentication": [

    • "#key-1"

    ]

  },
• "didDocumentMetadata": {

  • "created": "2024-07-26T19:27:03.379Z",
  • "version": 1,
  • "confirmed": true

  },
• "didDocumentData": { },
• "mdip": {

  • "version": 1,
  • "type": "string",
  • "registry": "TBTC"

  }

}

Remove an ID

path Parameters

id required

string

Responses

https://keychain.org/ids/{id}

Response samples

• 200

Content type

application/json

{

• "ok": true

}

Backup an ID

path Parameters

id required

string

Responses

https://keychain.org/ids/{id}/backup

Response samples

• 200

Content type

application/json

{

• "ok": true

}

Recover an DID

path Parameters

did required

string

Request Body schema: application/json

required

did

string

Responses

https://keychain.org/ids/{did}/recover

Request samples

• Payload

Content type

application/json

{

• "did": "string"

}

Response samples

• 200

Content type

application/json

{

• "recovered": "Bob"

}

Name

Name management routes

List all names

Responses

https://keychain.org/names

Response samples

• 200

Content type

application/json

{

• "names": {

  • "Alice": "did:test:z3v8AuajL3eA67e1kbHkRpwPAzBaoNxrWS2T3aM1Q7f96ScetCK",
  • "Bob": "did:test:z3v8AuajNV8UTtdm2X7PzmXvVrNP5iQTX2ebjsHkcF1NS9BCV7v",
  • "Carol": "did:test:z3v8AuaaZZqtVPZuHAqFkJhwKrcuAYaud8XA2MjrFYBth7ifELZ",
  • "Dave": "did:test:z3v8AuaUd8ExyT4ZfvRdPXzUWrsZqLAE9a8aiYUL7Fya4ncrK4p"

  }

}

Add a new name

Request Body schema: application/json

required

name	string
did	string

Responses

https://keychain.org/names

Request samples

• Payload

Content type

application/json

{

• "name": "string",
• "did": "string"

}

Response samples

• 200

Content type

application/json

{

• "ok": true

}

Resolve a name to DID

path Parameters

name required

string

Responses

https://keychain.org/names/{name}

Response samples

• 200

Content type

application/json

{

• "@context": "https://w3id.org/did-resolution/v1",
• "didDocument": {

  • "@context": [

    • "https://www.w3.org/ns/did/v1"

    ],
  • "id": "did:test:string",
  • "controller": "did:test:string"

  },
• "didDocumentMetadata": {

  • "created": "2024-07-26T19:53:44.468Z",
  • "version": 2,
  • "confirmed": true,
  • "updated": "2024-07-26T19:56:36.636Z"

  },
• "didDocumentData": {

  • "name": "string",
  • "members": [

    • "did:test:string"

    ]

  },
• "mdip": {

  • "version": 1,
  • "type": "string",
  • "registry": "string"

  }

}

Remove a name

path Parameters

name required

string

Responses

https://keychain.org/names/{name}

Response samples

• 200

Content type

application/json

{

• "ok": true

}

Challenge

Challenge and response routes

Create an empty challenge

Responses

https://keychain.org/challenge

Response samples

• 200

Content type

application/json

{

• "did": "did:test:z3v8Auaha4rszsBwMyApaY9eUR1pipjGASYvqqfuXiXhxA8DXmo"

}

Create a custom challenge

Request Body schema: application/json

required

challenge	object
options	object

Responses

https://keychain.org/challenge

Request samples

• Payload

Content type

application/json

{

• "challenge": { },
• "options": { }

}

Response samples

• 200

Content type

application/json

{

• "did": "did:test:z3v8Auaha4rszsBwMyApaY9eUR1pipjGASYvqqfuXiXhxA8DXmo"

}

Create a response to a challenge

Request Body schema: application/json

required

challenge	object
options	object

Responses

https://keychain.org/response

Request samples

• Payload

Content type

application/json

{

• "challenge": { },
• "options": { }

}

Response samples

• 200

Content type

application/json

{

• "did": "did:test:z3v8Auaha4rszsBwMyApaY9eUR1pipjGASYvqqfuXiXhxA8DXmo"

}

Verify a response

Request Body schema: application/json

required

response	object
options	object

Responses

https://keychain.org/response/verify

Request samples

• Payload

Content type

application/json

{

• "response": { },
• "options": { }

}

Response samples

• 200

Content type

application/json

{ }

Group

Group management routes

Create a new group

Request Body schema: application/json

required

name	string
options	object

Responses

https://keychain.org/groups

Request samples

• Payload

Content type

application/json

{

• "name": "string",
• "options": { }

}

Response samples

• 200

Content type

application/json

{

• "did": "did:test:z3v8Auaha4rszsBwMyApaY9eUR1pipjGASYvqqfuXiXhxA8DXmo"

}

Get a group

path Parameters

name required

string

Responses

https://keychain.org/groups/{name}

Response samples

• 200

Content type

application/json

{

• "name": "string",
• "members": [

  • "did:string"

  ]

}

Add a member to a group

path Parameters

name required

string

Request Body schema: application/json

required

member

string

Responses

https://keychain.org/groups/{name}/add

Request samples

• Payload

Content type

application/json

{

• "member": "string"

}

Response samples

• 200

Content type

application/json

{

• "ok": true

}

Remove a member from a group

path Parameters

name required

string

Request Body schema: application/json

required

member

string

Responses

https://keychain.org/groups/{name}/remove

Request samples

• Payload

Content type

application/json

{

• "member": "string"

}

Response samples

• 200

Content type

application/json

{

• "ok": true

}

Test if a member is in a group

path Parameters

name required

string

Request Body schema: application/json

required

member

string

Responses

https://keychain.org/groups/{name}/test

Request samples

• Payload

Content type

application/json

{

• "member": "string"

}

Response samples

• 200

Content type

application/json

{

• "test": true

}

Credential

Credential management routes

Bind a credential

Request Body schema: application/json

required

schema	object
subject	object
options	object

Responses

https://keychain.org/credentials/bind

Request samples

• Payload

Content type

application/json

{

• "schema": { },
• "subject": { },
• "options": { }

}

Response samples

• 200

Content type

application/json

{ }

List all held credentials

Responses

https://keychain.org/credentials/held

Response samples

• 200

Content type

application/json

{

• "held": [

  • "did:test:z3v8Auaha4rszsBwMyApaY9eUR1pipjGASYvqqfuXiXhxA8DXmo",
  • "did:test:z3v8AuajL3eA67e1kbHkRpwPAzBaoNxrWS2T3aM1Q7f96ScetCK",
  • "did:test:z3v8AuahRF4UhG5pvktQmnafoKa92pH5QUHZFuBp5qPcwj1jdqV"

  ]

}

Accept a credential

Request Body schema: application/json

required

did

string

Responses

https://keychain.org/credentials/held

Request samples

• Payload

Content type

application/json

{

• "did": "string"

}

Response samples

• 200

Content type

application/json

{

• "ok": true

}

Get a credential

path Parameters

did required

string

Responses

https://keychain.org/credentials/held/{did}

Response samples

• 200

Content type

application/json

{ }

Remove a credential

path Parameters

did required

string

Responses

https://keychain.org/credentials/held/{did}

Response samples

• 200

Content type

application/json

{

• "ok": true

}

Publish a credential

path Parameters

did required

string

Request Body schema: application/json

required

	object
reveal boolean

Responses

https://keychain.org/credentials/held/{did}/publish

Request samples

• Payload

Content type

application/json

{

• "options": {

  • "reveal": true

  }

}

Response samples

• 200

Content type

application/json

{

• "ok": true

}

Unpublish a credential

path Parameters

did required

string

Responses

https://keychain.org/credentials/held/{did}/unpublish

Response samples

• 200

Content type

application/json

{

• "ok": true

}

List all issued credentials

Responses

https://keychain.org/credentials/issued

Response samples

• 200

Content type

application/json

{

• "issued": [

  • "did:test:z3v8Auaha4rszsBwMyApaY9eUR1pipjGASYvqqfuXiXhxA8DXmo",
  • "did:test:z3v8AuajL3eA67e1kbHkRpwPAzBaoNxrWS2T3aM1Q7f96ScetCK",
  • "did:test:z3v8AuahRF4UhG5pvktQmnafoKa92pH5QUHZFuBp5qPcwj1jdqV"

  ]

}

Issue a credential

Request Body schema: application/json

required

credential	object
options	object

Responses

https://keychain.org/credentials/issued

Request samples

• Payload

Content type

application/json

{

• "credential": { },
• "options": { }

}

Response samples

• 200

Content type

application/json

{

• "did": "did:test:z3v8Auaha4rszsBwMyApaY9eUR1pipjGASYvqqfuXiXhxA8DXmo"

}

Get an issued credential

path Parameters

did required

string

Responses

https://keychain.org/credentials/issued/{did}

Response samples

• 200

Content type

application/json

{ }

Update an issued credential

path Parameters

did required

string

Responses

https://keychain.org/credentials/issued/{did}

Response samples

• 200

Content type

application/json

{

• "ok": true

}

Revoke an issued credential

path Parameters

did required

string

Responses

https://keychain.org/credentials/issued/{did}

Response samples

• 200

Content type

application/json

{

• "ok": true

}

Poll

Polling endpoints

Create a poll

Request Body schema: application/json

required

poll	object
options	object

Responses

https://keychain.org/polls

Request samples

• Payload

Content type

application/json

{

• "poll": { },
• "options": { }

}

Response samples

• 200

Content type

application/json

{

• "did": "did:test:z3v8Auaha4rszsBwMyApaY9eUR1pipjGASYvqqfuXiXhxA8DXmo"

}

View a poll

path Parameters

poll required

string

Responses

https://keychain.org/polls/{poll}/view

Response samples

• 200

Content type

application/json

{ }

Vote in a poll

Request Body schema: application/json

required

poll	string
vote	object
options	object

Responses

https://keychain.org/polls/vote

Request samples

• Payload

Content type

application/json

{

• "poll": "string",
• "vote": { },
• "options": { }

}

Response samples

• 200

Content type

application/json

{

• "did": "did:test:z3v8Auaha4rszsBwMyApaY9eUR1pipjGASYvqqfuXiXhxA8DXmo"

}

Update a poll

Request Body schema: application/json

required

ballot

object

Responses

https://keychain.org/polls/update

Request samples

• Payload

Content type

application/json

{

• "ballot": { }

}

Response samples

• 200

Content type

application/json

{

• "ok": true

}

Publish a poll

path Parameters

poll required

string

Request Body schema: application/json

required

options

object

Responses

https://keychain.org/polls/{poll}/publish

Request samples

• Payload

Content type

application/json

{

• "options": { }

}

Response samples

• 200

Content type

application/json

{

• "ok": true

}

Unpublish a poll

path Parameters

poll required

string

Responses

https://keychain.org/polls/{poll}/unpublish

Response samples

• 200

Content type

application/json

{

• "ok": true

}

Schemas

Schema endpoints

Create a template

path Parameters

id required

string

Request Body schema: application/json

required

schema

object

Responses

https://keychain.org/schemas/{id}/template

Request samples

• Payload

Content type

application/json

{

• "schema": { }

}

Response samples

• 200

Content type

application/json

{

• "did": "did:test:z3v8Auaha4rszsBwMyApaY9eUR1pipjGASYvqqfuXiXhxA8DXmo"

}

Create new schema

Request Body schema: application/json

required

schema	object
options	object

Responses

https://keychain.org/schemas

Request samples

• Payload

Content type

application/json

{

• "schema": { },
• "options": { }

}

Response samples

• 200

Content type

application/json

{

• "did": "did:test:z3v8Auaha4rszsBwMyApaY9eUR1pipjGASYvqqfuXiXhxA8DXmo"

}

List schemas

Responses

https://keychain.org/schemas

Response samples

• 200

Content type

application/json

{

• "schemas": [

  • "did:test:z3v8Auaha4rszsBwMyApaY9eUR1pipjGASYvqqfuXiXhxA8DXmo",
  • "did:test:z3v8AuajL3eA67e1kbHkRpwPAzBaoNxrWS2T3aM1Q7f96ScetCK",
  • "did:test:z3v8AuahRF4UhG5pvktQmnafoKa92pH5QUHZFuBp5qPcwj1jdqV"

  ]

}

Get a schema

path Parameters

id required

string

Responses

https://keychain.org/schemas/{id}

Response samples

• 200

Content type

application/json

{ }

Update a schema

path Parameters

id required

string

Responses

https://keychain.org/schemas/{id}

Response samples

• 200

Content type

application/json

{

• "ok": true

}

Test if id is a valid schema

path Parameters

id required

string

Request Body schema: application/json

required

schema

object

Responses

https://keychain.org/schemas/{id}/test

Request samples

• Payload

Content type

application/json

{

• "schema": { }

}

Response samples

• 200

Content type

application/json

{

• "test": true

}