Keymaster API

• getCheck if the Keymaster service is ready.
• getList the available registries.
• getRetrieve the current wallet.
• putSave the wallet.
• postCreate a new wallet.
• postCreate a backup of the current wallet.
• postRecover the wallet from an existing backup.
• postCheck the integrity of the wallet.
• postFix the wallet by removing invalid or deactivated entries.
• getDecrypt and retrieve the wallet's mnemonic phrase.
• getResolve a DID Document.
• delRevoke a DID.
• getRetrieve the current ID name.
• putSet the current ID.
• getList all ID names in the wallet.
• postCreate a new ID in the wallet.
• getResolve an ID to a DID Document.
• delRemove an existing ID from the wallet.
• postRename an existing ID in the wallet.
• postBackup the specified ID.
• postRecover an existing ID from a backup reference.
• getList all name-to-DID mappings in the wallet.
• postAdd a new name-to-DID mapping.
• getRetrieve the DID associated with a specific name.
• delRemove an existing name-to-DID mapping.
• getCreate a default challenge DID with no parameters.
• postCreate a challenge DID with custom data or options.
• postCreate a response to an existing challenge DID.
• postVerify a response to a challenge.
• getList all group DIDs owned by (or associated with) a specific ID.
• postCreate a new group asset (DID).
• getRetrieve an existing group.
• postAdd a member to an existing group.
• postRemove a member from an existing group.
• postTest membership in a group.
• getList all schema DIDs owned by (or associated with) a specific ID.
• postCreate a new schema.
• getRetrieve a stored schema.
• putUpdate an existing schema.
• postTest if a DID or name refers to a valid schema.
• postCheck whether the given ID (or DID) is an agent.
• postPrepare (bind) a credential without issuing it.
• getList all credentials currently held by the active ID.
• postAccept a credential into the "held" list of the current ID.
• getRetrieve (decrypt) a held credential.
• delRemove a credential from the "held" list.
• postPublish a held credential publicly.
• postRemove a published credential from the holder’s DID Document manifest.
• getList all credentials issued by the current ID.
• postIssue a new credential.
• getRetrieve an issued credential by DID.
• postUpdate an existing issued credential.
• delRevoke a previously issued credential.
• postRotate the current ID's keys.
• postEncrypt a plaintext message into a DID asset.
• postDecrypt an encrypted message asset by DID.
• postEncrypt a JSON object into a DID asset.
• postDecrypt a JSON asset by DID.
• postAdd a signature to a JSON object using the current ID's keys.
• postVerify a JSON object's signature.
• postGenerate a JSON template from a schema.
• postCreate a new asset DID.
• getList all asset DIDs owned by the current ID.
• getResolve (retrieve) an asset by DID or name.
• putUpdate an existing asset.
• postTransfer ownership of an asset.
• postClone an existing asset.
• getRetrieve a boilerplate poll template.
• getList polls owned by (or associated with) a given ID.
• postCreate a new poll.
• getRetrieve the raw poll data by DID or name.
• getCheck if a DID or name refers to a valid poll.
• getView detailed poll information, including results if the caller is the poll owner.
• postCast a vote in a poll.
• putRecord a received ballot in the poll.
• postPublish final poll results to the poll’s DID Document.
• postRemove previously published poll results from the poll's DID Document.
• postUpload an image and create a DID for it.
• putUpdate an existing image.
• getRetrieve an image by its DID.
• postTest if the specified image is valid.
• postUpload a binary document and create a DID for it.
• putUpdate an existing binary document.
• getRetrieve a binary document by its DID.
• postTest if the specified document is valid.
• getRetrieve data from the CAS (Content Addressable Storage)
• postCreate a new group vault.
• getRetrieve a group vault by DID.
• postTest if a DID refers to a valid group vault.
• postAdd a member to a group vault.
• getList all members of a group vault. (available only to group vault owner)
• delRemove a member from a group vault.
• postAdd an item to a group vault.
• getList all items in a group vault.
• delRemove an item from a group vault.
• getRetrieve an item from a group vault.
• getList all Dmail messages for the current or specified owner.
• postCreate a new Dmail message.
• postImport a Dmail message into the inbox.
• getRetrieve a Dmail message by DID.
• putUpdate an existing Dmail message.
• delRemove a Dmail message from the mailbox.
• postCreate a Notice and mark a Dmail message as sent.
• postFile (move) a Dmail message to a different folder by updating its tags.
• getList all attachments for a specific Dmail message.
• postAdd an attachment to a specific Dmail message.
• delRemove an attachment from a specific Dmail message.
• getDownload a specific attachment from a Dmail message.
• postCreate a new notice asset.
• putUpdate an existing notice asset.
• postRefresh all notices.

API docs by Redocly

Keymaster API (1.3.0)

Download OpenAPI specification:Download

Documentation for Keymaster API

Check if the Keymaster service is ready.

Returns a JSON object indicating the readiness status of the Keymaster service.

Responses

https://keychain.org/ready

Response samples

• 200
• 500

Content type

application/json

{

• "ready": true

}

List the available registries.

Responses

https://keychain.org/registries

Response samples

• 200
• 500

Content type

application/json

{

• "registries": [

  • "string"

  ]

}

Retrieve the current wallet.

Responses

https://keychain.org/wallet

Response samples

• 200
• 500

Content type

application/json

{

• "wallet": {

  • "seed": {

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

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

      }

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

    • "property1": {

      • "did": "string",
      • "account": 0,
      • "index": 0,
      • "owned": [

        • "string"

        ]

      },
    • "property2": {

      • "did": "string",
      • "account": 0,
      • "index": 0,
      • "owned": [

        • "string"

        ]

      }

    },
  • "current": "string",
  • "names": {

    • "property1": "string",
    • "property2": "string"

    }

  }

}

Save the wallet.

Request Body schema: application/json

required

required	object
object counter integer object current string object

Responses

https://keychain.org/wallet

Request samples

• Payload

Content type

application/json

{

• "wallet": {

  • "seed": {

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

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

      }

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

    • "property1": {

      • "did": "string",
      • "account": 0,
      • "index": 0,
      • "owned": [

        • "string"

        ]

      },
    • "property2": {

      • "did": "string",
      • "account": 0,
      • "index": 0,
      • "owned": [

        • "string"

        ]

      }

    },
  • "current": "string",
  • "names": {

    • "property1": "string",
    • "property2": "string"

    }

  }

}

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Create a new wallet.

Request Body schema: application/json

optional

mnemonic	string 12 words separated by a space (optional).
overwrite	boolean Default: false Whether to overwrite the existing wallet.

Responses

https://keychain.org/wallet/new

Request samples

• Payload

Content type

application/json

{

• "mnemonic": "string",
• "overwrite": false

}

Response samples

• 200
• 500

Content type

application/json

{

• "wallet": {

  • "seed": {

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

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

      }

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

    • "property1": {

      • "did": "string",
      • "account": 0,
      • "index": 0,
      • "owned": [

        • "string"

        ]

      },
    • "property2": {

      • "did": "string",
      • "account": 0,
      • "index": 0,
      • "owned": [

        • "string"

        ]

      }

    },
  • "current": "string",
  • "names": {

    • "property1": "string",
    • "property2": "string"

    }

  }

}

Create a backup of the current wallet.

Responses

https://keychain.org/wallet/backup

Response samples

• 200
• 500

Content type

application/json

{

• "ok": "string"

}

Recover the wallet from an existing backup.

Responses

https://keychain.org/wallet/recover

Response samples

• 200
• 500

Content type

application/json

{

• "wallet": {

  • "seed": {

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

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

      }

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

    • "property1": {

      • "did": "string",
      • "account": 0,
      • "index": 0,
      • "owned": [

        • "string"

        ]

      },
    • "property2": {

      • "did": "string",
      • "account": 0,
      • "index": 0,
      • "owned": [

        • "string"

        ]

      }

    },
  • "current": "string",
  • "names": {

    • "property1": "string",
    • "property2": "string"

    }

  }

}

Check the integrity of the wallet.

Responses

https://keychain.org/wallet/check

Response samples

• 200
• 500

Content type

application/json

{

• "check": {

  • "checked": 0,
  • "invalid": 0,
  • "deleted": 0

  }

}

Fix the wallet by removing invalid or deactivated entries.

Responses

https://keychain.org/wallet/fix

Response samples

• 200
• 500

Content type

application/json

{

• "fix": {

  • "idsRemoved": 0,
  • "ownedRemoved": 0,
  • "heldRemoved": 0,
  • "namesRemoved": 0

  }

}

Decrypt and retrieve the wallet's mnemonic phrase.

Responses

https://keychain.org/wallet/mnemonic

Response samples

• 200
• 500

Content type

application/json

{

• "mnemonic": "string"

}

Resolve a DID Document.

path Parameters

id required

string The DID or name to resolve.

query Parameters

atTime	string <date-time> Timestamp to return the state of the DID as of this specific time (RFC3339/ISO8601 format).
atVersion	integer Specific version of the DID Document to retrieve. Increments each time an update or delete operation occurs.
confirm	boolean If true, returns the DID Document only if it is fully confirmed on the registry it references.
verify	boolean If true, verifies the signature(s) of the DID operation(s) before returning the DID Document. If a signature is invalid, an error is thrown.

Responses

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

Response samples

• 200
• 404
• 500

Content type

application/json

{

• "docs": {

  • "@context": "string",
  • "didDocument": {

    • "@context": [

      • "string"

      ],
    • "id": "string",
    • "controller": "string",
    • "verificationMethod": [

      • {

        • "id": "string",
        • "controller": "string",
        • "type": "string",
        • "publicKeyJwk": { }

        }

      ],
    • "authentication": [

      • "string"

      ]

    },
  • "didDocumentMetadata": {

    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z",
    • "deleted": "2019-08-24T14:15:22Z",
    • "version": 0,
    • "versionId": "string",
    • "canonicalId": "string",
    • "confirmed": true,
    • "deactivated": true

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

    • "type": "agent",
    • "registry": "local",
    • "version": 0,
    • "validUntil": "2019-08-24T14:15:22Z",
    • "registration": "string"

    }

  }

}

Revoke a DID.

Removes an existing DID from the system, effectively revoking it.

path Parameters

id required

string The DID to revoke.

Responses

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

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Retrieve the current ID name.

Responses

https://keychain.org/ids/current

Response samples

• 200
• 500

Content type

application/json

{

• "current": "string"

}

Set the current ID.

Request Body schema: application/json

required

name required

string The name of the ID to set as current.

Responses

https://keychain.org/ids/current

Request samples

• Payload

Content type

application/json

{

• "name": "string"

}

Response samples

• 200
• 400

Content type

application/json

{

• "ok": true

}

List all ID names in the wallet.

Responses

https://keychain.org/ids

Response samples

• 200
• 500

Content type

application/json

{

• "ids": [

  • "string"

  ]

}

Create a new ID in the wallet.

Request Body schema: application/json

required

name	string The name of the new ID.
	object Optional parameters.

Responses

https://keychain.org/ids

Request samples

• Payload

Content type

application/json

{

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

  • "registry": "local"

  }

}

Response samples

• 200
• 500

Content type

application/json

{

• "did": "string"

}

Resolve an ID to a DID Document.

path Parameters

id required

string The name or DID to resolve.

Responses

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

Response samples

• 200
• 404
• 500

Content type

application/json

{

• "docs": { }

}

Remove an existing ID from the wallet.

path Parameters

id required

string The name of the ID to remove.

Responses

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

Response samples

• 200
• 400

Content type

application/json

{

• "ok": true

}

Rename an existing ID in the wallet.

path Parameters

id required

string The current name of the ID to be renamed.

Request Body schema: application/json

required

name required

string The new name for the ID.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "name": "string"

}

Response samples

• 200
• 400

Content type

application/json

{

• "ok": true

}

Backup the specified ID.

path Parameters

id required

string The ID name or DID to back up.

Responses

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

Response samples

• 200
• 400

Content type

application/json

{

• "ok": true

}

Recover an existing ID from a backup reference.

path Parameters

id required

string The ID name or DID to recover.

Responses

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

Response samples

• 200
• 404
• 500

Content type

application/json

{

• "recovered": "string"

}

List all name-to-DID mappings in the wallet.

Responses

https://keychain.org/names

Response samples

• 200
• 500

Content type

application/json

{

• "names": {

  • "property1": "string",
  • "property2": "string"

  }

}

Add a new name-to-DID mapping.

Request Body schema: application/json

required

name required	string The human-readable name to associate with the DID.
did required	string The DID that this name should refer to.

Responses

https://keychain.org/names

Request samples

• Payload

Content type

application/json

{

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

}

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Retrieve the DID associated with a specific name.

Returns the DID for the provided human-readable name, if it exists.

path Parameters

name required

string The name for which you want the associated DID.

Responses

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

Response samples

• 200
• 404

Content type

application/json

{

• "did": "string"

}

Remove an existing name-to-DID mapping.

path Parameters

name required

string The name whose mapping should be removed.

Responses

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

Response samples

• 200
• 400

Content type

application/json

{

• "ok": true

}

Create a default challenge DID with no parameters.

Responses

https://keychain.org/challenge

Response samples

• 200
• 500

Content type

application/json

{

• "did": "string"

}

Create a challenge DID with custom data or options.

Request Body schema: application/json

optional

challenge	object Arbitrary challenge data.
	object Additional options.

Responses

https://keychain.org/challenge

Request samples

• Payload

Content type

application/json

{

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

  • "registry": "local",
  • "validUntil": "2019-08-24T14:15:22Z"

  }

}

Response samples

• 200
• 400
• 500

Content type

application/json

{

• "did": "string"

}

Create a response to an existing challenge DID.

Accepts a challenge DID (the DID of a previously created challenge) and an options object, then returns a new DID containing the response. Internally, the Keymaster finds matching credentials and bundles them into verifiable presentations. The response is encrypted for the original challenge's controller and stored as a new asset DID.

Request Body schema: application/json

required

challenge	string DID of the challenge to respond to.
	object Additional parameters controlling how the response is created and stored.

Responses

https://keychain.org/response

Request samples

• Payload

Content type

application/json

{

• "challenge": "string",
• "options": {

  • "registry": "string",
  • "validUntil": "2019-08-24T14:15:22Z",
  • "retries": 0,
  • "delay": 1000,
  • "encryptForSender": true,
  • "includeHash": true,
  • "controller": "string"

  }

}

Response samples

• 200
• 400
• 500

Content type

application/json

{

• "did": "string"

}

Verify a response to a challenge.

Request Body schema: application/json

required

response	string DID of the challenge response asset to verify.
	object Additional verification parameters.

Responses

https://keychain.org/response/verify

Request samples

• Payload

Content type

application/json

{

• "response": "string",
• "options": {

  • "retries": 0,
  • "delay": 1000,
  • "atTime": "2019-08-24T14:15:22Z",
  • "atVersion": 0,
  • "confirm": true,
  • "verify": true

  }

}

Response samples

• 200
• 400
• 500

Content type

application/json

{

• "verify": {

  • "challenge": "string",
  • "credentials": [

    • { }

    ],
  • "match": true,
  • "vps": [

    • { }

    ],
  • "responder": "string"

  }

}

List all group DIDs owned by (or associated with) a specific ID.

query Parameters

owner

string The name or DID of the owner ID for which to list groups.

Responses

https://keychain.org/groups

Response samples

• 200
• 500

Content type

application/json

{

• "groups": [

  • "string"

  ]

}

Create a new group asset (DID).

Request Body schema: application/json

required

name	string The human-readable name of the group.
	object Additional parameters for creating the group.

Responses

https://keychain.org/groups

Request samples

• Payload

Content type

application/json

{

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

  • "members": [

    • "string"

    ],
  • "registry": "string",
  • "validUntil": "2019-08-24T14:15:22Z",
  • "retries": 0,
  • "delay": 1000,
  • "encryptForSender": true,
  • "includeHash": true,
  • "controller": "string"

  }

}

Response samples

• 200
• 500

Content type

application/json

{

• "did": "string"

}

Retrieve an existing group.

Returns the stored group object (including its name and members) for the given group DID or name.

path Parameters

name required

string The name or DID of the group to retrieve.

Responses

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

Response samples

• 200
• 404
• 500

Content type

application/json

{

• "group": {

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

    • "string"

    ]

  }

}

Add a member to an existing group.

Adds a DID (or group) as a member of the specified group.

path Parameters

name required

string The name or DID of the group to update.

Request Body schema: application/json

required

member required

string The DID (or group DID) to add as a member.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "member": "string"

}

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Remove a member from an existing group.

path Parameters

name required

string The name or DID of the group to update.

Request Body schema: application/json

required

member required

string The DID (or group DID) to remove from the group.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "member": "string"

}

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Test membership in a group.

path Parameters

name required

string The name or DID of the group to test.

Request Body schema: application/json

optional

member

string The DID or group DID to check for membership.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "member": "string"

}

Response samples

• 200
• 400

Content type

application/json

{

• "test": true

}

List all schema DIDs owned by (or associated with) a specific ID.

query Parameters

owner

string The name or DID of the owner whose schemas should be listed.

Responses

https://keychain.org/schemas

Response samples

• 200
• 500

Content type

application/json

{

• "schemas": [

  • "string"

  ]

}

Create a new schema.

Request Body schema: application/json

required

schema	object A valid JSON Schema to be stored.
	object Additional creation parameters.

Responses

https://keychain.org/schemas

Request samples

• Payload

Content type

application/json

{

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

  • "registry": "string",
  • "validUntil": "2019-08-24T14:15:22Z"

  }

}

Response samples

• 200
• 500

Content type

application/json

{

• "did": "string"

}

Retrieve a stored schema.

path Parameters

id required

string The name or DID of the schema to retrieve.

Responses

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

Response samples

• 200
• 404
• 500

Content type

application/json

{

• "schema": { }

}

Update an existing schema.

Replaces the schema (if valid) associated with the given DID or name. This operation will preserve the same DID while storing an updated schema in the underlying asset data.

path Parameters

id required

string The name or DID of the schema to update.

Request Body schema: application/json

required

schema

object The new JSON Schema to store.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "schema": { }

}

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Test if a DID or name refers to a valid schema.

Checks whether the given DID or name refers to an asset containing a valid JSON Schema. Returns true if it's a recognized valid schema, otherwise false.

path Parameters

id required

string The name or DID of the schema to test.

Request Body schema: application/json

optional

object

No required body parameters (reserved for future use).

Responses

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

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 200
• 400

Content type

application/json

{

• "test": true

}

Check whether the given ID (or DID) is an agent.

path Parameters

id required

string The ID name or DID to test.

Request Body schema: application/json

optional

object

No body required for this endpoint.

Responses

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

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 200
• 400

Content type

application/json

{

• "test": true

}

Prepare (bind) a credential without issuing it.

Request Body schema: application/json

required

schema	string The schema DID or name to which this credential conforms.
subject	string The subject DID (or name) for whom this credential is bound.
	object Optional parameters for credential creation.

Responses

https://keychain.org/credentials/bind

Request samples

• Payload

Content type

application/json

{

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

  • "credential": { },
  • "validFrom": "2019-08-24T14:15:22Z",
  • "validUntil": "2019-08-24T14:15:22Z"

  }

}

Response samples

• 200
• 400

Content type

application/json

{

• "credential": { }

}

List all credentials currently held by the active ID.

Responses

https://keychain.org/credentials/held

Response samples

• 200
• 500

Content type

application/json

{

• "held": [

  • "string"

  ]

}

Accept a credential into the "held" list of the current ID.

Request Body schema: application/json

required

did required

string The credential DID to hold.

Responses

https://keychain.org/credentials/held

Request samples

• Payload

Content type

application/json

{

• "did": "string"

}

Response samples

• 200
• 400

Content type

application/json

{

• "ok": true

}

Retrieve (decrypt) a held credential.

path Parameters

did required

string The credential DID to retrieve.

Responses

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

Response samples

• 200
• 500

Content type

application/json

{

• "credential": { }

}

Remove a credential from the "held" list.

path Parameters

did required

string The credential DID to remove from holdings.

Responses

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

Response samples

• 200
• 400

Content type

application/json

{

• "ok": true

}

Publish a held credential publicly.

path Parameters

did required

string The credential DID to publish from the holder's wallet.

Request Body schema: application/json

optional

	object Additional parameters controlling the publication.
reveal boolean Default: false Whether to include the full credential data or just a reference.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "options": {

  • "reveal": false

  }

}

Response samples

• 200
• 400

Content type

application/json

{

• "ok": { }

}

Remove a published credential from the holder’s DID Document manifest.

path Parameters

did required

string The credential DID to unpublish.

Request Body schema: application/json

optional

object

No additional parameters by default.

Responses

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

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 200
• 400

Content type

application/json

{

• "ok": "string"

}

List all credentials issued by the current ID.

Responses

https://keychain.org/credentials/issued

Response samples

• 200
• 500

Content type

application/json

{

• "issued": [

  • "string"

  ]

}

Issue a new credential.

Request Body schema: application/json

required

credential	object A valid credential object. If omitted, options.schema and options.subject can be used to generate one.
	object Additional issuance parameters.

Responses

https://keychain.org/credentials/issued

Request samples

• Payload

Content type

application/json

{

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

  • "schema": "string",
  • "subject": "string",
  • "registry": "string",
  • "validUntil": "2019-08-24T14:15:22Z",
  • "retries": 0,
  • "delay": 1000,
  • "encryptForSender": true,
  • "includeHash": true,
  • "controller": "string"

  }

}

Response samples

• 200
• 400

Content type

application/json

{

• "did": "string"

}

Retrieve an issued credential by DID.

path Parameters

did required

string The DID of the issued credential to retrieve.

Responses

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

Response samples

• 200
• 500

Content type

application/json

{

• "credential": { }

}

Update an existing issued credential.

path Parameters

did required

string The DID of the issued credential to update.

Request Body schema: application/json

required

credential required

object The new credential data to store.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "credential": { }

}

Response samples

• 200
• 400

Content type

application/json

{

• "ok": true

}

Revoke a previously issued credential.

path Parameters

did required

string The DID of the credential to revoke.

Responses

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

Response samples

• 200
• 400

Content type

application/json

{

• "ok": true

}

Rotate the current ID's keys.

Request Body schema: application/json

optional

object

No options required. Key rotation applies to the current ID.

Responses

https://keychain.org/keys/rotate

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Encrypt a plaintext message into a DID asset.

Request Body schema: application/json

required

msg	string The plaintext message to encrypt.
receiver	string The DID (or name) of the intended recipient.
	object Additional encryption/creation parameters.

Responses

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

Request samples

• Payload

Content type

application/json

{

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

  • "registry": "string",
  • "validUntil": "2019-08-24T14:15:22Z",
  • "retries": 0,
  • "delay": 1000,
  • "encryptForSender": true,
  • "includeHash": false,
  • "controller": "string"

  }

}

Response samples

• 200
• 500

Content type

application/json

{

• "did": "string"

}

Decrypt an encrypted message asset by DID.

Request Body schema: application/json

required

did required

string The DID representing the encrypted asset.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "did": "string"

}

Response samples

• 200
• 500

Content type

application/json

{

• "message": "string"

}

Encrypt a JSON object into a DID asset.

Request Body schema: application/json

required

json	object The JSON object to be encrypted.
receiver	string The DID (or name) of the intended recipient.
	object Additional encryption/creation parameters (same fields as /keys/encrypt/message).

Responses

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

Request samples

• Payload

Content type

application/json

{

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

  • "registry": "string",
  • "validUntil": "2019-08-24T14:15:22Z",
  • "retries": 0,
  • "delay": 1000,
  • "encryptForSender": true,
  • "includeHash": false,
  • "controller": "string"

  }

}

Response samples

• 200
• 500

Content type

application/json

{

• "did": "string"

}

Decrypt a JSON asset by DID.

Request Body schema: application/json

required

did required

string The DID representing the encrypted JSON asset.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "did": "string"

}

Response samples

• 200
• 500

Content type

application/json

{

• "json": { }

}

Add a signature to a JSON object using the current ID's keys.

Request Body schema: application/json

required

contents required

string A JSON string representing the data to be signed.

Responses

https://keychain.org/keys/sign

Request samples

• Payload

Content type

application/json

{

• "contents": "string"

}

Response samples

• 200
• 500

Content type

application/json

{

• "signed": { }

}

Verify a JSON object's signature.

Request Body schema: application/json

required

json required

object The signed JSON object to verify, which must include a signature property.

Responses

https://keychain.org/keys/verify

Request samples

• Payload

Content type

application/json

{

• "json": { }

}

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Generate a JSON template from a schema.

Creates a JSON template object based on the specified schema. The template will include placeholder values that conform to the schema's structure and constraints.

path Parameters

id required

string The name or DID of the schema from which to generate a template.

Responses

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

Response samples

• 200
• 404
• 500

Content type

application/json

{

• "template": { }

}

Create a new asset DID.

Request Body schema: application/json

required

data	object Arbitrary data to store in this asset.
	object Additional creation parameters.

Responses

https://keychain.org/assets

Request samples

• Payload

Content type

application/json

{

• "data": { },
• "options": {

  • "registry": "string",
  • "validUntil": "2019-08-24T14:15:22Z",
  • "controller": "string",
  • "name": "string"

  }

}

Response samples

• 200
• 500

Content type

application/json

{

• "did": "string"

}

List all asset DIDs owned by the current ID.

Responses

https://keychain.org/assets

Response samples

• 200
• 500

Content type

application/json

{

• "assets": [

  • "string"

  ]

}

Resolve (retrieve) an asset by DID or name.

path Parameters

id required

string The asset name or DID to resolve.

Responses

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

Response samples

• 200
• 404

Content type

application/json

{

• "asset": { }

}

Update an existing asset.

path Parameters

id required

string The asset DID or name to update.

Request Body schema: application/json

required

data	object The new data to store in this asset's DID Document.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "data": { }

}

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Transfer ownership of an asset.

Transfers the ownership of the specified asset (identified by its DID or name) to a new controller.

path Parameters

id required

string The DID or name of the asset to transfer.

Request Body schema: application/json

required

controller required

string The DID of the new controller to transfer ownership to.

Responses

https://keychain.org/assets/{id}/transfer

Request samples

• Payload

Content type

application/json

{

• "controller": "string"

}

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Clone an existing asset.

Creates a new asset by cloning the data of an existing asset identified by its DID or name. The cloned asset will include a reference to the original asset in its metadata.

path Parameters

id required

string The DID or name of the asset to clone.

Request Body schema: application/json

optional

	object Additional parameters for cloning the asset.
registry string The registry in which to create the cloned asset (e.g., "local", "hyperswarm"). validUntil string <date-time> Expiration timestamp for the cloned asset.

Responses

https://keychain.org/assets/{id}/clone

Request samples

• Payload

Content type

application/json

{

• "options": {

  • "registry": "string",
  • "validUntil": "2019-08-24T14:15:22Z"

  }

}

Response samples

• 200
• 500

Content type

application/json

{

• "did": "string"

}

Retrieve a boilerplate poll template.

Responses

https://keychain.org/templates/poll

Response samples

• 200
• 500

Content type

application/json

{

• "template": {

  • "type": "string",
  • "version": 0,
  • "description": "string",
  • "roster": "string",
  • "options": [

    • "string"

    ],
  • "deadline": "2019-08-24T14:15:22Z"

  }

}

List polls owned by (or associated with) a given ID.

query Parameters

owner

string The name or DID of the owner ID to list polls for.

Responses

https://keychain.org/polls

Response samples

• 200
• 500

Content type

application/json

{

• "polls": [

  • "string"

  ]

}

Create a new poll.

Request Body schema: application/json

required

	object The poll definition containing the required fields.
	object Additional parameters for poll creation.

Responses

https://keychain.org/polls

Request samples

• Payload

Content type

application/json

{

• "poll": {

  • "type": "poll",
  • "version": 1,
  • "description": "string",
  • "roster": "string",
  • "options": [

    • "string",
    • "string"

    ],
  • "deadline": "2019-08-24T14:15:22Z"

  },
• "options": {

  • "registry": "string",
  • "validUntil": "2019-08-24T14:15:22Z",
  • "retries": 0,
  • "delay": 1000,
  • "encryptForSender": true,
  • "includeHash": false,
  • "controller": "string"

  }

}

Response samples

• 200
• 500

Content type

application/json

{

• "did": "string"

}

Retrieve the raw poll data by DID or name.

path Parameters

poll required

string The DID or name of the poll to retrieve.

Responses

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

Response samples

• 200
• 500

Content type

application/json

{

• "poll": { }

}

Check if a DID or name refers to a valid poll.

path Parameters

poll required

string The DID or name of the poll to test.

Responses

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

Response samples

• 200
• 500

Content type

application/json

{

• "test": true

}

View detailed poll information, including results if the caller is the poll owner.

path Parameters

poll required

string The DID or name of the poll to view.

Responses

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

Response samples

• 200
• 500

Content type

application/json

{

• "poll": { }

}

Cast a vote in a poll.

Casts a vote in the specified poll. The vote is recorded as a ballot DID, which should be submitted to the poll owner.

path Parameters

poll required

string The DID or name of the poll to vote in.

Request Body schema: application/json

required

vote required	integer The numerical option index (1-based). Use 0 or set spoil in options to cast a spoiled ballot.
	object Additional vote parameters.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "vote": 0,
• "options": {

  • "spoil": false,
  • "registry": "string",
  • "validUntil": "2019-08-24T14:15:22Z",
  • "retries": 0,
  • "delay": 1000,
  • "encryptForSender": false,
  • "includeHash": false,
  • "controller": "string"

  }

}

Response samples

• 200
• 500

Content type

application/json

{

• "did": "string"

}

Record a received ballot in the poll.

Request Body schema: application/json

required

ballot required

string The DID of the ballot to record in the poll.

Responses

https://keychain.org/polls/update

Request samples

• Payload

Content type

application/json

{

• "ballot": "string"

}

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Publish final poll results to the poll’s DID Document.

path Parameters

poll required

string The DID or name of the poll to publish.

Request Body schema: application/json

optional

	object Publication parameters.
reveal boolean Default: false If true, includes all ballots. If false, only the summary is published.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "options": {

  • "reveal": false

  }

}

Response samples

• 200
• 500

Content type

application/json

{

• "ok": { }

}

Remove previously published poll results from the poll's DID Document.

path Parameters

poll required

string The DID or name of the poll to unpublish.

Request Body schema: application/json

optional

object

No additional parameters, unless needed for future expansions.

Responses

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

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Upload an image and create a DID for it.

Uploads an image as binary data and creates a DID for it. Additional options can be passed via the X-Options header.

header Parameters

X-Options

string A JSON string containing additional options for the image creation process. Example: {"registry":"local","validUntil":"2025-12-31T23:59:59Z"}

Request Body schema: application/octet-stream

required

The image data to store as a DID asset.

string <binary>

Responses

https://keychain.org/images

Response samples

• 200
• 500

Content type

application/json

{

• "did": "string"

}

Update an existing image.

Updates the binary data of an existing image identified by its DID.

path Parameters

id required

string The DID of the image to update.

Request Body schema: application/octet-stream

required

The new image data to replace the existing one.

string <binary>

Responses

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

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Retrieve an image by its DID.

Fetches the image data and metadata associated with the specified DID.

path Parameters

id required

string The DID of the image to retrieve.

Responses

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

Response samples

• 200
• 404

Content type

application/json

{

• "image": {

  • "type": "string",
  • "width": 0,
  • "height": 0,
  • "bytes": 0,
  • "cid": "string"

  }

}

Test if the specified image is valid.

Checks whether the image associated with the given DID is valid or meets specific criteria.

path Parameters

id required

string The DID of the image to test.

Responses

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

Response samples

• 200
• 400

Content type

application/json

{

• "test": true

}

Upload a binary document and create a DID for it.

Accepts binary data as the request body and creates a DID for the uploaded document. Additional options can be passed via the X-Options header.

header Parameters

X-Options

string A JSON string containing additional options for the document creation process. Example: {"registry":"local","validUntil":"2025-12-31T23:59:59Z"}

Request Body schema: application/octet-stream

required

The binary document data to store as a DID asset.

string <binary>

Responses

https://keychain.org/documents

Response samples

• 200
• 500

Content type

application/json

{

• "did": "string"

}

Update an existing binary document.

Updates the binary data of an existing document identified by its DID. Additional options can be passed via the X-Options header.

path Parameters

id required

string The DID of the document to update.

header Parameters

X-Options

string A JSON string containing additional options for the document update process. Example: {"registry":"local","validUntil":"2025-12-31T23:59:59Z"}

Request Body schema: application/octet-stream

required

The new binary document data to replace the existing one.

string <binary>

Responses

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

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Retrieve a binary document by its DID.

Fetches the binary document data and metadata associated with the specified DID.

path Parameters

id required

string The DID of the document to retrieve.

Responses

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

Response samples

• 200
• 404

Content type

application/json

{

• "document": {

  • "type": "string",
  • "bytes": 0,
  • "cid": "string"

  }

}

Test if the specified document is valid.

Checks whether the document associated with the given DID is valid or meets specific criteria.

path Parameters

id required

string The DID of the document to test.

Responses

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

Response samples

• 200
• 400

Content type

application/json

{

• "test": true

}

Retrieve data from the CAS (Content Addressable Storage)

path Parameters

cid required

string The CID (Content Identifier) of the data to retrieve

Responses

https://keychain.org/cas/data/{cid}

Response samples

• 404
• 500

Content type

application/json

"Not Found"

Create a new group vault.

Creates a new group vault asset and returns its DID.

Request Body schema: application/json

required

	object Additional options for group vault creation.
registry string The registry in which to create the group vault DID (e.g., "local", "hyperswarm"). validUntil string <date-time> Optional expiration date/time for the group vault.

Responses

https://keychain.org/groupVaults

Request samples

• Payload

Content type

application/json

{

• "options": {

  • "registry": "string",
  • "validUntil": "2019-08-24T14:15:22Z"

  }

}

Response samples

• 200
• 500

Content type

application/json

{

• "did": "string"

}

Retrieve a group vault by DID.

Returns the group vault object for the specified DID.

path Parameters

id required

string The DID of the group vault to retrieve.

Responses

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

Response samples

• 200
• 404

Content type

application/json

{

• "groupVault": {

  • "publicJwk": { },
  • "salt": "string",
  • "keys": {

    • "property1": "string",
    • "property2": "string"

    },
  • "items": "string"

  }

}

Test if a DID refers to a valid group vault.

Checks whether the specified DID or name refers to a valid group vault asset.

path Parameters

id required

string The DID or name of the group vault to test.

Responses

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

Response samples

• 200
• 404

Content type

application/json

{

• "test": true

}

Add a member to a group vault.

Adds a new member to the specified group vault if the caller has permission.

path Parameters

id required

string The DID of the group vault.

Request Body schema: application/json

required

memberId required

string The DID of the member to add to the group vault.

Responses

https://keychain.org/groupVaults/{id}/members

Request samples

• Payload

Content type

application/json

{

• "memberId": "string"

}

Response samples

• 200
• 404

Content type

application/json

{

• "ok": true

}

List all members of a group vault. (available only to group vault owner)

Returns an object containing all member DIDs of the specified group vault.

path Parameters

id required

string The DID of the group vault.

Responses

https://keychain.org/groupVaults/{id}/members

Response samples

• 200
• 404

Content type

application/json

{

• "members": {

  • "property1": { },
  • "property2": { }

  }

}

Remove a member from a group vault.

Removes the specified member from the group vault if the caller has permission.

path Parameters

id required	string The DID of the group vault.
member required	string The DID of the member to remove from the group vault.

Responses

https://keychain.org/groupVaults/{id}/members/{member}

Response samples

• 200
• 404

Content type

application/json

{

• "ok": true

}

Add an item to a group vault.

Adds a new item (binary data) to the specified group vault. The item name must be provided in the X-Options header as JSON.

path Parameters

id required

string The DID of the group vault.

header Parameters

X-Options required

string A JSON string containing additional options, including the item name. Example: {"name":"myfile.txt"}

Request Body schema: application/octet-stream

required

string <binary>

Responses

https://keychain.org/groupVaults/{id}/items

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

List all items in a group vault.

Returns an index of all items stored in the specified group vault.

path Parameters

id required

string The DID of the group vault.

Responses

https://keychain.org/groupVaults/{id}/items

Response samples

• 200
• 404

Content type

application/json

{

• "items": {

  • "property1": { },
  • "property2": { }

  }

}

Remove an item from a group vault.

Deletes the specified item from the group vault if the caller has permission.

path Parameters

id required	string The DID of the group vault.
name required	string The name of the item to remove from the group vault.

Responses

https://keychain.org/groupVaults/{id}/items/{name}

Response samples

• 200
• 404

Content type

application/json

{

• "ok": true

}

Retrieve an item from a group vault.

Returns the binary data for a specific item stored in the group vault.

path Parameters

id required	string The DID of the group vault.
name required	string The name of the item to retrieve from the group vault.

Responses

https://keychain.org/groupVaults/{id}/items/{name}

Response samples

• 404

Content type

application/json

{

• "error": "string"

}

List all Dmail messages for the current or specified owner.

Returns a mapping of Dmail DIDs to Dmail item objects for the current wallet or for the specified owner.

query Parameters

owner

string The name or DID of the owner whose Dmail messages should be listed.

Responses

https://keychain.org/dmail

Response samples

• 200
• 500

Content type

application/json

{

• "dmail": {

  • "property1": { },
  • "property2": { }

  }

}

Create a new Dmail message.

Request Body schema: application/json

required

message	object The Dmail message object to create.
options	object Additional creation options (e.g., registry, validUntil).

Responses

https://keychain.org/dmail

Request samples

• Payload

Content type

application/json

{

• "message": {

  • "to": [

    • "did:mdip:abc123",
    • "did:mdip:def456"

    ],
  • "cc": [

    • "did:mdip:ghi789"

    ],
  • "subject": "Hello World",
  • "body": "This is a test Dmail message."

  },
• "options": { }

}

Response samples

• 200
• 500

Content type

application/json

{

• "did": "string"

}

Import a Dmail message into the inbox.

Request Body schema: application/json

required

did	string The DID of the Dmail message to import.

Responses

https://keychain.org/dmail/import

Request samples

• Payload

Content type

application/json

{

• "did": "string"

}

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Retrieve a Dmail message by DID.

path Parameters

id required

string The DID of the Dmail message to retrieve.

Responses

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

Response samples

• 200
• 404

Content type

application/json

{

• "message": { }

}

Update an existing Dmail message.

path Parameters

id required

string The DID of the Dmail message to update.

Request Body schema: application/json

required

message

object The updated Dmail message object.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "message": { }

}

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Remove a Dmail message from the mailbox.

path Parameters

id required

string The DID of the Dmail message to remove.

Responses

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

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Create a Notice and mark a Dmail message as sent.

path Parameters

id required

string The DID of the Dmail message to send.

Responses

https://keychain.org/dmail/{id}/send

Response samples

• 200
• 500

Content type

application/json

{

• "did": "string"

}

File (move) a Dmail message to a different folder by updating its tags.

Updates the tags of a Dmail message, allowing it to be moved between folders such as inbox, archive, or trash.

path Parameters

id required

string The DID of the Dmail message to file.

Request Body schema: application/json

required

tags required

Array of strings The new tags to assign to the Dmail message (e.g., ["inbox"], ["archived"], ["deleted"]).

Responses

https://keychain.org/dmail/{id}/file

Request samples

• Payload

Content type

application/json

{

• "tags": [

  • "string"

  ]

}

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

List all attachments for a specific Dmail message.

Returns a mapping of attachment names to their metadata for the specified Dmail DID.

path Parameters

id required

string The DID of the Dmail message whose attachments should be listed.

Responses

https://keychain.org/dmail/{id}/attachments

Response samples

• 200
• 404

Content type

application/json

{

• "attachments": {

  • "property1": { },
  • "property2": { }

  }

}

Add an attachment to a specific Dmail message.

Uploads a binary attachment and associates it with the specified Dmail message. The attachment name must be provided in the X-Options header as JSON.

path Parameters

id required

string The DID of the Dmail message to attach the file to.

header Parameters

X-Options required

string A JSON string containing additional options, including the attachment name. Example: {"name":"myfile.txt"}

Request Body schema: application/octet-stream

required

string <binary>

Responses

https://keychain.org/dmail/{id}/attachments

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Remove an attachment from a specific Dmail message.

Deletes the specified attachment from the Dmail message identified by its DID.

path Parameters

id required	string The DID of the Dmail message.
name required	string The name of the attachment to remove.

Responses

https://keychain.org/dmail/{id}/attachments/{name}

Response samples

• 200
• 404

Content type

application/json

{

• "ok": true

}

Download a specific attachment from a Dmail message.

Returns the binary data for the specified attachment associated with the given Dmail DID.

path Parameters

id required	string The DID of the Dmail message.
name required	string The name of the attachment to download.

Responses

https://keychain.org/dmail/{id}/attachments/{name}

Response samples

• 404

Content type

application/json

"string"

Create a new notice asset.

Creates a new notice asset (e.g., for Dmail delivery) and returns its DID.

Request Body schema: application/json

required

message	object The NoticeMessage object to create.
options	object Additional creation options (e.g., registry, validUntil).

Responses

https://keychain.org/notices

Request samples

• Payload

Content type

application/json

{

• "message": {

  • "to": [

    • "did:mdip:abc123",
    • "did:mdip:def456"

    ],
  • "dids": [

    • "did:mdip:dmail1",
    • "did:mdip:dmail2"

    ]

  },
• "options": { }

}

Response samples

• 200
• 500

Content type

application/json

{

• "did": "string"

}

Update an existing notice asset.

Updates the NoticeMessage data for the specified notice DID.

path Parameters

id required

string The DID of the notice to update.

Request Body schema: application/json

required

message

object The updated NoticeMessage object.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "message": {

  • "to": [

    • "did:mdip:abc123",
    • "did:mdip:def456"

    ],
  • "dids": [

    • "did:mdip:dmail1",
    • "did:mdip:dmail2"

    ]

  }

}

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}

Refresh all notices.

Refreshes the state of all notice assets, updating any that have changed.

Responses

https://keychain.org/notices/refresh

Response samples

• 200
• 500

Content type

application/json

{

• "ok": true

}