Gatekeeper API

• getCheck if the Gatekeeper service is ready.
• getRetrieve the API version
• getRetrieve server status
• postCreate, update, or delete a DID
• getResolve a DID Document
• postUpdate an existing DID (deprecated)
• delDelete a DID (deprecated)
• postRetrieve a list of DIDs or DID Documents.
• postRemove one or more DIDs
• postExport events for one or more DIDs
• postImport one or more DIDs
• postExport non-local DID events in a single sorted batch
• postImport a batch of DID events
• getRetrieve the queued events for a specific registry
• postRemove specified DIDs from the queue
• getRetrieve supported registries
• getReset the database
• getVerify all DIDs in the database
• postProcess queued events
• postAdds a JSON object to the CAS (Content Addressable Storage)
• getRetrieve a JSON object from the CAS (Content Addressable Storage)
• postAdds text to the CAS (Content Addressable Storage)
• getRetrieve text from the CAS (Content Addressable Storage)
• postAdds an octet-stream to the CAS (Content Addressable Storage)
• getRetrieve data from the CAS (Content Addressable Storage)
• getRetrieve the latest block for a specific registry
• getRetrieve a specific block for a given registry
• postAdd a new block to a specific registry

API docs by Redocly

Gatekeeper API (1.3.0)

Download OpenAPI specification:Download

Documentation for Keymaster API

Check if the Gatekeeper service is ready.

Responses

https://keychain.org/ready

Retrieve the API version

Responses

https://keychain.org/version

Response samples

• 200

Content type

application/json

0

0

Retrieve server status

Responses

https://keychain.org/status

Response samples

• 200

Content type

application/json

{

• "uptimeSeconds": 0,
• "dids": {

  • "total": 0,
  • "byType": {

    • "agents": 0,
    • "assets": 0,
    • "confirmed": 0,
    • "unconfirmed": 0,
    • "ephemeral": 0,
    • "invalid": 0

    },
  • "byRegistry": {

    • "property1": 0,
    • "property2": 0

    },
  • "byVersion": {

    • "property1": 0,
    • "property2": 0

    },
  • "eventsQueue": { }

  },
• "memoryUsage": {

  • "rss": 0,
  • "heapTotal": 0,
  • "heapUsed": 0,
  • "external": 0,
  • "arrayBuffers": 0

  }

}

Create, update, or delete a DID

Request Body schema: application/json

required

One of

type required	string Value: "create" Must be "create" to create a new DID.
created required	string <date-time> Timestamp of when the operation was created.
required	object MDIP metadata fields for creation.
required	object Cryptographic signature verifying the create operation.
publicJwk	object Required if mdip.type = "agent". Contains the public key in JWK format.
controller	string Required if mdip.type = "asset". Must match the signer in signature.

Responses

https://keychain.org/did

Request samples

• Payload

Content type

application/json

{

• "type": "delete",
• "did": "string",
• "signature": {

  • "value": "string",
  • "signed": "2019-08-24T14:15:22Z",
  • "signer": "string",
  • "hash": "string"

  }

}

Response samples

• 500

Content type

application/json

"string"

Resolve a DID Document

path Parameters

did required

string The DID to resolve.

query Parameters

atTime	string <date-time> Timestamp to return the state of the DID as of this specific time.
atVersion	integer Specific version of the DID Document to retrieve. Versioning increments each time an update or delete operation occurs.
confirm	boolean If true, returns the DID Document if it is fully confirmed.
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/{did}

Response samples

• 200
• 404

Content type

application/json

{

• "@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"

  }

}

Update an existing DID (deprecated) Deprecated

path Parameters

did required

string The DID to update.

Request Body schema: application/json

required

type required	string Value: "update" Must be "update" for this operation.
did required	string The DID being updated. Must match the path parameter {did}.
doc	object The updated DID Document or subset of data for this DID.
previd	string Reference to the previous version.
signature required	object Cryptographic signature.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "type": "update",
• "did": "string",
• "doc": { },
• "previd": "string",
• "signature": { }

}

Response samples

• 200
• 500

Content type

application/json

true

Delete a DID (deprecated) Deprecated

path Parameters

did required

string The DID to delete.

Request Body schema: application/json

required

type required	string Value: "delete" Must be "delete" to deactivate the DID.
did required	string The DID being deleted.
signature required	object Cryptographic signature.
previd	string Reference to the previous version.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "type": "delete",
• "did": "string",
• "signature": { },
• "previd": "string"

}

Response samples

• 200

Content type

application/json

true

Retrieve a list of DIDs or DID Documents.

Request Body schema: application/json

optional

dids	Array of strings A list of specific DIDs to check. If omitted, all known DIDs are retrieved.
updatedAfter	string <date-time> Only return DIDs/DID Docs updated after this time.
updatedBefore	string <date-time> Only return DIDs/DID Docs updated before this time.
confirm	boolean If true, only return DID Docs that are fully confirmed.
verify	boolean If true, verifies signatures during DID resolution. If signature checks fail, an error is thrown.
resolve	boolean If true, return DID Documents instead of just string identifiers.

Responses

https://keychain.org/dids/

Request samples

• Payload

Content type

application/json

{

• "dids": [

  • "string"

  ],
• "updatedAfter": "2019-08-24T14:15:22Z",
• "updatedBefore": "2019-08-24T14:15:22Z",
• "confirm": true,
• "verify": true,
• "resolve": true

}

Response samples

• 200
• 500

Content type

application/json

[ ]

Remove one or more DIDs

Request Body schema: application/json

required

Array

string

A valid DID.

Responses

https://keychain.org/dids/remove

Request samples

• Payload

Content type

application/json

[

• "string"

]

Response samples

• 200
• 500

Content type

application/json

true

Export events for one or more DIDs

Request Body schema: application/json

optional

dids	Array of strings A list of DIDs to export. If omitted, all known DIDs are exported.

Responses

https://keychain.org/dids/export

Request samples

• Payload

Content type

application/json

{

• "dids": [

  • "string"

  ]

}

Response samples

• 200
• 500

Content type

application/json

[

• [

  • {

    • "registry": "string",
    • "time": "2019-08-24T14:15:22Z",
    • "ordinal": 0,
    • "operation": { },
    • "did": "string"

    }

  ]

]

Import one or more DIDs

Request Body schema: application/json

required

Array

Array

did required	string The DID these events belong to.
required	object The DID operation including signatures and other data.
registry required	string The registry this event belongs to.
time required	string <date-time> Timestamp when this event was recorded.
	integer or Array of integers

Responses

https://keychain.org/dids/import

Request samples

• Payload

Content type

application/json

[

• [

  • {

    • "did": "string",
    • "operation": {

      • "type": "string",
      • "created": "2019-08-24T14:15:22Z",
      • "mdip": { },
      • "publicJwk": { },
      • "signature": { }

      },
    • "registry": "string",
    • "time": "2019-08-24T14:15:22Z",
    • "ordinal": 0

    }

  ]

]

Response samples

• 200
• 500

Content type

application/json

{

• "queued": 0,
• "processed": 0,
• "rejected": 0,
• "total": 0

}

Export non-local DID events in a single sorted batch

Request Body schema: application/json

optional

dids	Array of strings A list of DIDs to export. If omitted, all known DIDs are used for exporting.

Responses

https://keychain.org/batch/export

Request samples

• Payload

Content type

application/json

{

• "dids": [

  • "string"

  ]

}

Response samples

• 200
• 500

Content type

application/json

[

• {

  • "registry": "string",
  • "time": "2019-08-24T14:15:22Z",
  • "ordinal": 0,
  • "operation": {

    • "type": "string",
    • "did": "string",
    • "signature": { }

    },
  • "did": "string"

  }

]

Import a batch of DID events

Request Body schema: application/json

required

Array

did required	string The DID to which this event pertains.
required	object A DID operation, such as "create", "update", or "delete".
registry required	string The registry to which this event belongs.
time required	string <date-time> Timestamp when the event was recorded.
	integer or Array of integers

Responses

https://keychain.org/batch/import

Request samples

• Payload

Content type

application/json

[

• {

  • "did": "string",
  • "operation": {

    • "type": "create",
    • "created": "2019-08-24T14:15:22Z",
    • "mdip": { },
    • "publicJwk": { },
    • "signature": { }

    },
  • "registry": "local",
  • "time": "2019-08-24T14:15:22Z",
  • "ordinal": 0

  }

]

Response samples

• 200
• 500

Content type

application/json

{

• "queued": 0,
• "processed": 0,
• "rejected": 0,
• "total": 0

}

Retrieve the queued events for a specific registry

path Parameters

registry required

string The name of the registry whose queue is being retrieved. Valid values may include "local", "hyperswarm", "TBTC", "TFTC", etc.

Responses

https://keychain.org/queue/{registry}

Response samples

• 200
• 500

Content type

application/json

[

• {

  • "registry": "string",
  • "time": "2019-08-24T14:15:22Z",
  • "ordinal": 0,
  • "operation": {

    • "type": "string",
    • "did": "string",
    • "signature": { }

    },
  • "did": "string"

  }

]

Remove specified DIDs from the queue

path Parameters

registry required

string The name of the registry from which events will be cleared. Must be a valid, supported registry.

Request Body schema: application/json

required

Array

type required	string The operation type.
did required	string The DID targeted by this operation.
doc	object The (optional) DID document content, present if type is "update" or "create" with doc data.
previd	string Reference to the previous version (optional).
signature required	object Cryptographic signature.

Responses

https://keychain.org/queue/{registry}/clear

Request samples

• Payload

Content type

application/json

[

• {

  • "type": "string",
  • "did": "string",
  • "doc": { },
  • "previd": "string",
  • "signature": { }

  }

]

Response samples

• 200
• 500

Content type

application/json

[

• { }

]

Retrieve supported registries

Responses

https://keychain.org/registries

Response samples

• 200
• 500

Content type

application/json

[

• "string"

]

Reset the database

Responses

https://keychain.org/db/reset

Response samples

• 200
• 500

Content type

application/json

true

Verify all DIDs in the database

Responses

https://keychain.org/db/verify

Response samples

• 200
• 500

Content type

application/json

{

• "total": 0,
• "verified": 0,
• "expired": 0,
• "invalid": 0

}

Process queued events

Iterates over all queued events, importing them if they are valid (adding or merging). Continues until no more new events can be processed. If processEvents is already running, it may return { busy: true } to indicate that processing is in progress.

Responses

https://keychain.org/events/process

Response samples

• 200
• 500

Content type

application/json

{

• "added": 0,
• "merged": 0,
• "rejected": 0,
• "pending": 0

}

Adds a JSON object to the CAS (Content Addressable Storage)

Request Body schema: application/json

required

The JSON object to store in the CAS

object

Responses

https://keychain.org/cas/json

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 500

Content type

application/json

"string"

Retrieve a JSON object from the CAS (Content Addressable Storage)

path Parameters

cid required

string The CID (Content Identifier) of the JSON object to retrieve

Responses

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

Response samples

• 200
• 404
• 500

Content type

application/json

{ }

Adds text to the CAS (Content Addressable Storage)

Request Body schema: text/plain

required

The text to store in the CAS

string

Responses

https://keychain.org/cas/text

Response samples

• 500

Content type

application/json

"string"

Retrieve text from the CAS (Content Addressable Storage)

path Parameters

cid required

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

Responses

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

Response samples

• 404
• 500

Content type

application/json

"Not Found"

Adds an octet-stream to the CAS (Content Addressable Storage)

Request Body schema: application/octet-stream

required

The data to store in the CAS

string <binary>

Responses

https://keychain.org/cas/data

Response samples

• 500

Content type

application/json

"string"

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"

Retrieve the latest block for a specific registry

path Parameters

registry required

string The name of the registry to retrieve the latest block from.

Responses

https://keychain.org/block/{registry}/latest

Response samples

• 200
• 500

Content type

application/json

{

• "hash": "string",
• "height": 0,
• "time": 0

}

Retrieve a specific block for a given registry

path Parameters

registry required	string The name of the registry to retrieve the block from.
required	string or integer The identifier of the block to retrieve. Can be either a block hash (string) or a block height (integer).

Responses

https://keychain.org/block/{registry}/{blockId}

Response samples

• 200
• 500

Content type

application/json

{

• "hash": "string",
• "height": 0,
• "time": 0,
• "timeISO": "2019-08-24T14:15:22Z"

}

Add a new block to a specific registry

path Parameters

registry required

string The name of the registry to which the block will be added.

Request Body schema: application/json

required

hash required	string The hash of the block.
height required	integer The height of the block.
time required	integer The timestamp of the block in seconds since the Unix epoch.

Responses

https://keychain.org/block/{registry}

Request samples

• Payload

Content type

application/json

{

• "hash": "string",
• "height": 0,
• "time": 0

}

Response samples

• 200
• 500

Content type

application/json

true