Payload cURL

The Dock Certs API

A complete solution for creating, managing and presenting Verifiable Credentials.

The Dock Certs API allows you to issue, verify and revoke verifiable credentials, manage DIDs and interact with the Dock blockchain. Dock integrates industry-leading World Wide Web Consortium (W3C) and VCDM standards, allowing it to interoperate with other open source technologies. We provide a range of open-source software on GitHub that can be used alongside the API. Primary features include:

In addition to the code samples shown in these docs, we have provided various code samples for the common requests that you can easily access here.

We also offer a free trial, testnet sandboxing and fair monthly pricing. Sign up and start issuing credentials with Dock Certs. Please read our Terms of Service before using Dock Certs.

Example Use Case

Tim is a newly graduated Lawyer from the University of Chicago, looking for an opportunity to grow his career. With the use of verifiable credentials, Tim is issued a certificate proving his qualifications from the university, the certificate resides on Tim’s mobile device.

Details of the certificate reside in the Verifiable Credential and the proof of identity of the university (which is the decentralized identifier) is stored on the blockchain. The University can also opt to create a record (called an anchor) of the credential on the blockchain with a timestamp.

When Tim applies for jobs, the process of:

Changes to:

The new process of validating and authenticating credentials is instantaneous and leaves no room for error and tampering.

Participants in the Process

Issuer

The issuer in the scenario above is the university. The educational institution providing the certificate. They also have the power to revoke the credential if necessary.

Holder

The owner of the credential, Tim has the certificate proving his qualifications on his mobile device and can share and send it to whomever he wishes.

Verifier

The workplace where Tim wants to work. They are the ones who need to verify Tim’s qualifications and can instantly do this.

Getting Started

Prerequisites

You must first have an account and acquire your credentials (API keys) before accessing the Dock Certs API. You can register an account and generate a key in your Dock Certs dashboard.

Endpoints

Dock Certs provides two endpoints based on which mode was selected when creating your API key. By default, the API keys are created for production. You can switch to test mode in Dock Certs by clicking the test mode toggle in the top right next to your avatar icon. Once in test mode you will see only testnet transactions, API keys, webhooks etc. You can then create an API key from the Dock Certs dashboard. It should be noted that in test mode your used transaction count will not increase or hit monthly limits allowing for sandboxing on our test network.

IMPORTANT NOTES:

Authentication

Dock Certs uses API keys to authenticate requests. You can obtain an API Key by signing into Dock Certs. Once a key has been generated, it should be included in all request headers as below:

Architecture Style

Dock Certs is built using a REST architecture. Our API uses standard HTTP response codes, authentication, delivers JSON-encoded responses, accepts form-encoded request bodies, and accepts form-encoded request bodies.

HTTPS is required for all API requests. Requests performed via plain HTTP will be rejected. API requests that do not include authentication will also fail. JSON requests should typically be encoded as UTF-8.

HTTP Method Description
GET Gets one or many resources
POST Creates a new resources
PATCH Partially updates a resource
DELETE Deletes a resource

Rate Limits

We allow you to make up to 200 requests in a 2 minute window (avg 100 reqs/min or 1.6 reqs/second). If you exceed beyond that, you will receive a 429 Too Many Requests response and have to wait up to a minute for the next request depending on when you hit the limit. If you require higher rate limits, please contact us.

Error Handling

The Dock Certs API uses standard HTTP response codes to indicate if an API request was successful or unsuccessful.

The table below shows the most frequent HTTP error messages:

Code Meaning
400 Bad Request -- Your request was rejected (e.g., missing mandatory field).
402 Payment required -- Transaction limit reached or upgrade required to proceed
401 Unauthorized -- Do not own resource or have an invalid API key in the header.
404 Not Found -- The resource that you're trying to interact with could not be found on the server.
405 Method Not Allowed -- The requested method does not exist in the API spec. Please check the {did} value and ensure that it's not empty/blank.
429 Too Many Requests -- You sent too many requests. Please try to reduce the number of requests.
500 Server Errors -- Something has gone wrong on the server. Contact us if this keeps happening.

Terminology

It is important to fully understand all the terminologies within the Dock ecosystem. The following are common terminologies within our ecosystem:

Terminology Description
DID DID stands for Decentralized Identifier. It is a new type of identifier that enables verifiable, decentralized digital identity. A DID refers to any subject (e.g., a person, organization, thing, data model, abstract entity, etc.) as determined by the controller of the DID. For more information, please refer here.
Anchoring A feature that allows users to store a digest of one or more credentials (or any files) on our blockchain so that they are associated with immutable timestamps and hence can be proven to have been created at a certain point in time.
Data Schema The structure that describes the logical view of the data. It is useful to enforce a specific structure on a collection of data like a Verifiable Credential.
Registries A process to verify credentials in such a way that each verified credential has its own unique number. This process references a credential definition and specifies how revocation of that credential type will be handled. 
Schema The structure of credentials which are shareable among issuers as they do not contain any cryptographic material and thus are created less frequently.
Blob Blob stands for Binary Large OBject. It is a collection of binary data stored as a single entity. The schemas are identified and retrieved by their unique blob id, which is a 32-byte long hex string.
DID Resolver The tool that initiates the process of learning the DID document.

Webhooks

We provide webhooks for asynchronous integration with the API. You can configure a webhook to receive notifications whenever events occur within the API (see below for the list of published events). To use our webhook, you need to set the webhook URL that acts as a receiver receiving the information whenever an event happens. You also need to select at least one of the webhook events from Dock Certs to trigger the data exchange.

How to Setup Webhook

To setup webhook, simply follow the steps below:

Webhook Events

You can configure the following events to trigger the HTTP request to send the data to your application.

SAMPLE JSON PAYLOAD

{
  "token": "4A_Z0fYD19q1qKZ03qAfB0zTu8XYuLPpGk0oHfP8OrvGGDi5Jz8C86F6EVz8Wd2c",
  "event": "anchor_create",
  "data": {
    "status": "finalized",
    "encodedTx": "0x90040f008082f112f7575ff922ffa2290c9b11e071cc45a79b3cc1d3de66d0be819fe7e808",
    "result": {
      "InBlock": "0xbaf1bfcc5b629b775a4d03c9baa0b0d6d7197fe1ab1805993d38da3447661c76"
    }
  }
}

anchor_create

This event indicates an anchor has been created. It will fire when an anchor has been created.

SAMPLE JSON PAYLOAD

{
  "token": "4A_Z0fYD19q1qKZ03qAfB0zTu8XYuLPpGk0oHfP8OrvGGDi5Jz8C86F6EVz8Wd2c",
  "event": "credential_create",
  "data": {
    "id": "http://example.com/39",
    "signingOps": 1,
    "byteSize": 727,
    "key": "did:dock:5DhSFTFJwD6bFdrPdTibhxQypDruZkBGeWs1p34FS87ko5Vy#5GsBC74MW9DxHkFUYDVGPnbtioEaFgPgkdytQU3cRTQcHJCz",
    "credential": {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1"
      ],
      "id": "https://creds.dock.io/f087cbfabc90f8b996971ba47598e82b1a03523cb9460217ad58a819cd9c09eb",
      "type": [
        "VerifiableCredential"
      ],
      "credentialSubject": {
        "id": "did:dock:5DhSFTFJwD6bFdrPdTibhxQypDruZkBGeWs1p34FS87ko5Vy"
      },
      "issuanceDate": "2019-08-24T14:15:22Z",
      "expirationDate": "2019-08-24T14:15:22Z",
      "proof": {
        "type": "Sr25519Signature2020",
        "created": "2021-11-23T03:16:47Z",
        "verificationMethod": "did:dock:5DhSFTFJwD6bFdrPdTibhxQypDruZkBGeWs1p34FS87ko5Vy#keys-1",
        "proofPurpose": "assertionMethod",
        "proofValue": "z4jUYjc4CyQSfVCivjjTpngjg9TsSL5GkdNesqQFBxwtZwgruophe7xaAzFMSx2gZt4CmXhhhWz4aEyA9wtpqwhdn"
      },
      "issuer": {
        "id": "did:dock:5DhSFTFJwD6bFdrPdTibhxQypDruZkBGeWs1p34FS87ko5Vy",
        "name": "Issuer Name"
      }
    }
  }
}

credential_create

This event indicates a credential has been created. It will fire when a credential has been created.

SAMPLE JSON PAYLOAD

{
  "token": "4A_Z0fYD19q1qKZ03qAfB0zTu8XYuLPpGk0oHfP8OrvGGDi5Jz8C86F6EVz8Wd2c",
  "event": "credential_issued",
  "data": {
    "id": "http://example.com/39",
    "signingOps": 1,
    "byteSize": 691,
    "key": "did:dock:5DhSFTFJwD6bFdrPdTibhxQypDruZkBGeWs1p34FS87ko5Vy#5GsBC74MW9DxHkFUYDVGPnbtioEaFgPgkdytQU3cRTQcHJCz",
    "credential": {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1"
      ],
      "id": "https://creds.dock.io/f087cbfabc90f8b996971ba47598e82b1a03523cb9460217ad58a819cd9c09eb",
      "type": [
        "VerifiableCredential"
      ],
      "credentialSubject": {
        "id": "did:dock:5DhSFTFJwD6bFdrPdTibhxQypDruZkBGeWs1p34FS87ko5Vy"
      },
      "issuanceDate": "2021-11-23T03:16:25.321Z",
      "proof": {
        "type": "Sr25519Signature2020",
        "created": "2021-11-23T03:16:25Z",
        "verificationMethod": "did:dock:5DhSFTFJwD6bFdrPdTibhxQypDruZkBGeWs1p34FS87ko5Vy#keys-1",
        "proofPurpose": "assertionMethod",
        "proofValue": "z41DNxuUzSvKz68L2YkXehR3nQ9PWoAfj6zk44gUzFXKK7pd2zEQByYAUGGg5TT2cZCxiYAmg49NGMX8tRLyf9W1G"
      },
      "issuer": {
        "id": "did:dock:5DhSFTFJwD6bFdrPdTibhxQypDruZkBGeWs1p34FS87ko5Vy",
        "name": "Issuer Name"
      }
    }
  }
}

credential_issued

This event indicates a credential has been issued. It will fire when a credential has been issued.

SAMPLE JSON PAYLOAD

{
  "token": "4A_Z0fYD19q1qKZ03qAfB0zTu8XYuLPpGk0oHfP8OrvGGDi5Jz8C86F6EVz8Wd2c",
  "event": "credential_revoke",
  "data": {
    "status": "finalized",
    "encodedTx": "0xa902040a0153b52f6bac3d812853d8aad9c94eb98b4a5dd632c5bf805dc4140965c753641e04aff1aa6770d43d684690c0ad679a8608d5b7576feb3fdc1d6712decf73ca44efd3ec3b0004483fc667eb8a63f8e040bb91cd23f6c650fb668d0152390a026620d05c5168ed00787db3a6322a4d81ab64848fdb4ec7f76404ad2360075b64e2de1c3d4bb0f2624d4684d073e528367a2dba2379254a50be816afa7eb731fa4f4807f1c6b4548f",
    "result": {
      "InBlock": "0x759314aa18d741335ac809ca2d877aed0a00375c3ba4a7dfc398d80dbc7bf2d5"
    }
  }
}

credential_revoke

This event indicates a credential has been revoked. It will fire when a credential has been revoked.

SAMPLE JSON PAYLOAD

{
  "token": "4A_Z0fYD19q1qKZ03qAfB0zTu8XYuLPpGk0oHfP8OrvGGDi5Jz8C86F6EVz8Wd2c",
  "event": "credential_unrevoke",
  "data": {
    "status": "finalized",
    "encodedTx": "0xa902040a0253b52f6bac3d812853d8aad9c94eb98b4a5dd632c5bf805dc4140965c753641e04aff1aa6770d43d684690c0ad679a8608d5b7576feb3fdc1d6712decf73ca44ef45ed3b0004483fc667eb8a63f8e040bb91cd23f6c650fb668d0152390a026620d05c5168ed0052ced1926bc978029cf9ebe9107450961ca8f0aed21033b61087a901271e1451c67a1f8feb7851f8dda0913223fc3bb5a26b9550014dccce61b5392e9a5e3181",
    "result": {
      "InBlock": "0x4279f477c280d1721efaee8a3ee621f3d96068fe978811db73d4ab27fecc687a"
    }
  }
}

credential_unrevoke

This event indicates a credential has been unrevoked. It will fire when a credential has been unrevoked.

SAMPLE JSON PAYLOAD

{
  "token": "4A_Z0fYD19q1qKZ03qAfB0zTu8XYuLPpGk0oHfP8OrvGGDi5Jz8C86F6EVz8Wd2c",
  "event": "did_create",
  "data": {
    "status": "finalized",
    "encodedTx": "0x91010409004e0d07d7121cbfb78be48fea337f7afd6f90aa233e33c17ab8137c4873c7da924e0d07d7121cbfb78be48fea337f7afd6f90aa233e33c17ab8137c4873c7da920012e604ac480aa06981c9b5dae4fc0e0bd8961fd858584e0a53f8a66e9b5e1648",
    "result": {
      "InBlock": "0xe5f17466a3c4b2ac3f455d923367e6e2baf9970583c2ed56299280d3a269a471"
    }
  }
}

did_create

This event indicates a DID has been created. It will fire when a DID has been created.

SAMPLE JSON PAYLOAD

{
  "token": "4A_Z0fYD19q1qKZ03qAfB0zTu8XYuLPpGk0oHfP8OrvGGDi5Jz8C86F6EVz8Wd2c",
  "event": "did_update_key",
  "data": {
    "status": "finalized",
    "encodedTx": "0xa902040901c7f54544fc24f652c4bfd1eded6e26d4400cd2cc91f130f85076aee6f1f6efb2001eabe8649baa2de3ee613dd488a433f743ed36854843e2aef4317a924118487201483fc667eb8a63f8e040bb91cd23f6c650fb668d0152390a026620d05c5168ed15293c000030af292a54c9ac95c999dd746ae61b6f35e1b8e610a637ef7d8710c093826e6d7a01d665bbcc8e4825830711371dade0f78b604b39fa864e92911ed030e15181",
    "result": {
      "InBlock": "0x8c876bd6fe0dbbadc91ed04a5d9f811dca02850f95dda409e558034df24177bb"
    }
  }
}

did_update_key

This event indicates a keyType value within the DID has been updated. It will fire when the keyType value has been updated.

SAMPLE JSON PAYLOAD

{
  "token": "4A_Z0fYD19q1qKZ03qAfB0zTu8XYuLPpGk0oHfP8OrvGGDi5Jz8C86F6EVz8Wd2c",
  "event": "did_update_controller",
  "data": {
    "status": "finalized",
    "encodedTx": "0xad02040901c81cd739fdd090d889280f04ddec47cad8240290e974319eaf1a7d7f10213c500203d5dc1a348b80aa06673fc36b8d1c0405125ad61d90c43e157815cc0779a8696801483fc667eb8a63f8e040bb91cd23f6c650fb668d0152390a026620d05c5168ed822b3c000139a87a45eaf9ada41c964bada887ebffa7bf34d66aec88821fb7a6d2177d634e83ab7a45f685835add00cebcc96a8c572e2833ad01d6dcacb0f72fb9bf80fa0a",
    "result": {
      "InBlock": "0x47c6640633a8a22df1de8fdc8e80f36dc403e735975e6f14d1a30419a18a6abd"
    }
  }
}

did_update_controller

This event indicates a controller value within the DID has been updated. It will fire when the controller value has been updated.

SAMPLE JSON PAYLOAD

{
  "token": "4A_Z0fYD19q1qKZ03qAfB0zTu8XYuLPpGk0oHfP8OrvGGDi5Jz8C86F6EVz8Wd2c",
  "event": "did_delete",
  "data": {
    "status": "finalized",
    "encodedTx": "0xa1010409024e0d07d7121cbfb78be48fea337f7afd6f90aa233e33c17ab8137c4873c7da92c0ea3b000008dcdfb22efd01604ca38facdb6c1086f2d76c2a36425f293e4c687e48f0ea295e02162e8af53f334544676bbf906f12f60d36a0b42dad89e169bc2816d68a85",
    "result": {
      "InBlock": "0x588b2170d114f68f47d697b92c4c2184db26deada7e114f205a6bb95a157a3bd"
    }
  }
}

did_delete

This event indicates a DID has been deleted. It will fire when a DID has been deleted.

SAMPLE JSON PAYLOAD

{
  "token": "4A_Z0fYD19q1qKZ03qAfB0zTu8XYuLPpGk0oHfP8OrvGGDi5Jz8C86F6EVz8Wd2c",
  "event": "registry_create",
  "data": {
    "status": "finalized",
    "encodedTx": "0x1901040a0035cbd5b17285e74b86b198543f712c03c99b75d7e2ed82923fa1fde7f1129ef40004483fc667eb8a63f8e040bb91cd23f6c650fb668d0152390a026620d05c5168ed00",
    "result": {
      "InBlock": "0x2407aa20e16ae915698888ed84f41d1bc06d3733ed17c89041b897e91ecf8fac"
    }
  }
}

registry_create

This event indicates a registry has been created. It will fire when a registry has been created.

SAMPLE JSON PAYLOAD

{
  "token": "4A_Z0fYD19q1qKZ03qAfB0zTu8XYuLPpGk0oHfP8OrvGGDi5Jz8C86F6EVz8Wd2c",
  "event": "registry_delete",
  "data": {
    "status": "finalized",
    "encodedTx": "0x2502040a0335cbd5b17285e74b86b198543f712c03c99b75d7e2ed82923fa1fde7f1129ef443ec3b0004483fc667eb8a63f8e040bb91cd23f6c650fb668d0152390a026620d05c5168ed00405a766d239405e6e3c63104581168cbb831e32299f7af72e39b5e8774631674f41595542249599a454ce957374be99fc061ec40200d380a8df1776e4417fa82",
    "result": {
      "InBlock": "0x4c58ebd08823a2dd5d776eaed526bfeddacf988d79c8e85cd807e8765622de7a"
    }
  }
}

registry_delete

This event indicates a registry has been deleted. It will fire when a registry has been deleted.

SAMPLE JSON PAYLOAD

{
  "token": "4A_Z0fYD19q1qKZ03qAfB0zTu8XYuLPpGk0oHfP8OrvGGDi5Jz8C86F6EVz8Wd2c",
  "event": "schema_create",
  "data": {
    "status": "finalized",
    "encodedTx": "0xa106040b00e1420661c333988c024f0a4bd3ea4ed0e75773247a369419acdaa67447c22ca489047b2224736368656d61223a22687474703a2f2f6a736f6e2d736368656d612e6f72672f64726166742d30372f736368656d6123222c226164646974696f6e616c50726f70657274696573223a66616c73652c226465736372697074696f6e223a22446f636b20536368656d61204578616d706c65222c2270726f70657274696573223a7b22616c756d6e694f66223a7b2274797065223a22737472696e67227d2c22656d61696c41646472657373223a7b22666f726d6174223a22656d61696c222c2274797065223a22737472696e67227d2c226964223a7b2274797065223a22737472696e67227d7d2c227265717569726564223a5b22656d61696c41646472657373222c22616c756d6e694f66225d2c2274797065223a226f626a656374227d483fc667eb8a63f8e040bb91cd23f6c650fb668d0152390a026620d05c5168ed00c2d11f1a68160f1a7d926c7c89a937866d70fdd0b5d350a6b2be88ad099a8776c6518e1d798553f596baff8d3be36d0172860e7a9b1368019339c7da05bf3485",
    "result": {
      "InBlock": "0x8b7042e52223334929e1cb2507e9be5b35014573dbe693bbcda2952f6254934f"
    }
  }
}

schema_create

This event indicates a schema has been created. It will fire when a schema has been created.

Dock Postman Collection

Download and use our Postman Collection to experiment with basic API flows:

Simple E2E Create Credentials/Presentation Flow

This flow refers to Postman, but the general steps are the same however you use the API. The Postman collection includes the scripts that automatically propagate results into the next request bodies when you follow the below steps. To issue a credential and or a presentation on the holder's behalf, the following steps are required:

DID CREATED - 200 Response

{
    "id": "823",
    "data": {
        "did": "did:dock:5FDFd1Woa3cG1m18PLgPpYgGfwE5S1RqXyHeEYC86vUxzzkg",
        "hexDid": "0x8b3997a95f86c80e5eb8a4ab67dbb164d5cc19ea24c072a85a3eb0d552fa837f",
        "controller": "did:dock:5FDFd1Woa3cG1m18PLgPpYgGfwE5S1RqXyHeEYC86vUxzzkg"
    }
}

1. Create a DID

To create a new DID to issue with, go to Create DID and click Send. The id property denotes a job ID in the system that you can use to query for blockchain transaction status.

The Dock API supports did:dock, did:polygonid and did:key method creation.

DID VERIFIED - 200 Response

{
    "@context": "https://www.w3.org/ns/did/v1",
    "id": "did:dock:5FDFd1Woa3cG1m18PLgPpYgGfwE5S1RqXyHeEYC86vUxzzkg",
    "authentication": [
        "did:dock:5FDFd1Woa3cG1m18PLgPpYgGfwE5S1RqXyHeEYC86vUxzzkg#keys-1"
    ],
    "assertionMethod": [
        "did:dock:5FDFd1Woa3cG1m18PLgPpYgGfwE5S1RqXyHeEYC86vUxzzkg#keys-1"
    ],
    "publicKey": [ ... ]
}

2. Verify the New DID

To verify if the new DID has been registered, go to Verify DID Registered and click Send.

CREDENTIAL ISSUED - 200 Response

{
    "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "id": "https://creds.dock.io/f087cbfabc90f8b996971ba47598e82b1a03523cb9460217ad58a819cd9c09eb",
    "type": [
        "VerifiableCredential"
    ],
    "credentialSubject": {
        "id": "did:dock:5FDFd1Woa3cG1m18PLgPpYgGfwE5S1RqXyHeEYC86vUxzzkg"
    },
    "issuanceDate": "2021-11-12T14:43:46.504Z",
    "proof": { ... },
    "issuer": { ... }
}

3. Create a Signed Credential

To create a Verifiable Credential using the the new issuer DID, go to Create Signed Credential and click Send. This will send some example credential data to the API and sign it with your DID keypair. It will return a Verifiable Credential that conforms to the W3C spec.

CREDENTIAL VERIFIED - 200 Response

{
    "verified": true,
    "results": [ ... ]
}

4. Verify the Signed Credential

To verify if the credential's cryptographic proof, revocation status and more go to Verify Signed Credential and click Send.

PRESENTATION CREATED - 200 Response

{
    "@context": [
        "https://www.w3.org/2018/credentials/v1"
    ],
    "verifiableCredential": [
        {
            "@context": [
                "https://www.w3.org/2018/credentials/v1",
                "https://www.w3.org/2018/credentials/examples/v1"
            ],
            "id": "https://creds.dock.io/f087cbfabc90f8b996971ba47598e82b1a03523cb9460217ad58a819cd9c09eb",
            "type": [
                "VerifiableCredential"
            ],
            "credentialSubject": {
                "id": "did:dock:5FDFd1Woa3cG1m18PLgPpYgGfwE5S1RqXyHeEYC86vUxzzkg"
            },
            "issuanceDate": "2021-11-12T14:43:46.504Z",
            "proof": { ... },
            "issuer": { ... }
        }
    ],
    "id": "https://creds.dock.io/presentation/adfb13f1a4b8934d0e94d2aa507e006c",
    "type": [
        "VerifiablePresentation"
    ],
    "proof": { ... }
}

5. Create a Presentation

To create a Verifiable Presentation by using the credential, go to Create Presentation and click Send.

PRESENTATION VERIFIED - 200 Response

{
    "verified": true,
    "results": []
}

6. Verify the Presentation

The same credential verification route can be used to verify a presentation. In Postman, go to Verify Presentation and click Send.

Dock Swagger UI

Dock Swagger UI generates interactive API documentation to try out the API calls directly in any browser. Use our Swagger UI to execute the API calls quickly:

DIDs

Endpoints

DID stands for Decentralized IDentifiers. DIDs are meant to be globally unique identifiers that allow their owner to prove cryptographic control over them. A DID identifies any subject (e.g., a person, organization, thing, data model, abstract entity, etc.) that the controller of the DID decides that it identifies.

DIDs in Dock are created by choosing a 32-byte unique (on Dock chain) identifier along with a public key. You can update and delete a DID as well as list all DIDs. DID is identified by a unique, random key.

For a detailed example of the DIDs workflow. Please refer here.

Create DID

POST /dids REQUEST

curl --location --request POST 'https://api.dock.io/dids' \
--header 'DOCK-API-TOKEN: API_KEY' \
--data-raw '{
  "type": "dock",
  "keyType": "ed25519"
}'

{
  "type": "dock",
  "keyType": "ed25519"
}

A DID, a public key, and a controller are required to create a new DID. The controller is both the owner of the public key and a DID. The DID can be created using an auto-generated keypair, and the controller will be the same as the DID unless otherwise specified. The DID and public key have no cryptographic relation.

It is important to have a public key of one of its three supported types. Dock supports 3 types of public keys: sr25519, ed25519, and secp256k1.

Parameters

Name In Type Required Description
did body DIDDock false DID as fully qualified, e.g., did:dock:. Default value will is a randomly generated DID.
type body string false Specifies the DID method to for the generated DID. Supported options are key, polygonid and dock (default).
controller body DIDDock false DID as fully qualified, e.g., did:dock:. The default value of the controller is the did property.
keyType body KeyType false Type of public key for DID. The default value of the keyType is sr25519.

Enumerated Values

Parameter Value Desctiprion
keyType sr25519 or ed25519 or secp256k1 or bjj keyType signature variants.
type dock or key or polyginid which DID method to generate

200 Response

{
  "id": "926",
  "data": {
    "did": "did:dock:5DTGPqE2qYncxoDjrEWKhcTnn6hfsN24F7YZWSjGVUxgBgHA",
    "hexDid": "0x3d7129a4d915e8f864c4bf4f4bcbdb67cde87e9bbcec06cb3baefd5b31812c03",
    "controller": "did:dock:5DTGPqE2qYncxoDjrEWKhcTnn6hfsN24F7YZWSjGVUxgBgHA"
  }
}

Responses

Status Meaning Description Schema
200 OK The request was successful and will try to create DID. NOTE: DID does not exist on network until the job identified in the response is complete. JobStartedResult
400 Bad Request The request was unsuccessful, because of invalid params. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

Get DID

GET /dids/{did} REQUEST

curl --location --request GET 'https://api.dock.io/dids/did:dock:xyz' \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''

When a DID is provided in the path, the API will attempt to resolve that DID into a DID document. This document contains the public keys and more information relating to that DID, check the identity foundation did configuration document to learn more.

The API supports resolving many DID methods, some examples are:

Parameters

Name In Type Required Description
did path DIDDock true Represents a specific DID that uniquely identifies the key resource.

200 Response

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:dock:5EEepQGeAeWnYgV8DWj5pH7pjHqrP2ZN2oBiE6ND2ZHA1dyN",
  "authentication": [
    "did:dock:5EEepQGeAeWnYgV8DWj5pH7pjHqrP2ZN2oBiE6ND2ZHA1dyN#keys-1"
  ],
  "assertionMethod": [
    "did:dock:5EEepQGeAeWnYgV8DWj5pH7pjHqrP2ZN2oBiE6ND2ZHA1dyN#keys-1"
  ],
  "publicKey": [
    {
      "id": "did:dock:5EEepQGeAeWnYgV8DWj5pH7pjHqrP2ZN2oBiE6ND2ZHA1dyN#keys-1",
      "type": "Sr25519VerificationKey2020",
      "controller": "did:dock:5EEepQGeAeWnYgV8DWj5pH7pjHqrP2ZN2oBiE6ND2ZHA1dyN",
      "publicKeyBase58": "ZY7vx2Jg1NSpEyrfGpDm7mRxNZyoYtbjjCjhHbhPtzM"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK The request was successful and will return the DID doc.
404 Not Found The requested DID was not found. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

List DIDs

GET /dids REQUEST

curl --location --request GET 'https://api.dock.io/dids' \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''

Return a list of all DIDs that your user account controls as fully resolved DID documents.

200 Response

[
  {
    "@context": "https://www.w3.org/ns/did/v1",
    "id": "did:dock:5DTGPqE2qYncxoDjrEWKhcTnn6hfsN24F7YZWSjGVUxgBgHA",
    "authentication": [
      "did:dock:5DTGPqE2qYncxoDjrEWKhcTnn6hfsN24F7YZWSjGVUxgBgHA#keys-1"
    ],
    "assertionMethod": [
      "did:dock:5DTGPqE2qYncxoDjrEWKhcTnn6hfsN24F7YZWSjGVUxgBgHA#keys-1"
    ],
    "publicKey": [
      {
        "id": "did:dock:5DTGPqE2qYncxoDjrEWKhcTnn6hfsN24F7YZWSjGVUxgBgHA#keys-1",
        "type": "Sr25519VerificationKey2020",
        "controller": "did:dock:5DTGPqE2qYncxoDjrEWKhcTnn6hfsN24F7YZWSjGVUxgBgHA",
        "publicKeyBase58": "4vm85LvBvhro1N9u4dfKWEyTayXojrTJbJCmzSJixK6L"
      }
    ]
  }
]

Parameters

Name In Type Required Description
offset query integer false How many items to offset by for pagination
limit query integer false How many items to return at one time (max 64)

Responses

Status Meaning Description Schema
200 OK All of a user's DIDs fully resolved into DID documents. DIDDock
402 Payment required Transaction limit reached or upgrade required to proceed Error

Delete DID

DELETE /dids/{did} REQUEST

curl --location --request DELETE https://api.dock.io/dids/{did} \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    }'

Deletes a DID and its metadata from the blockchain and our platform. This will also delete the associated keypair from the key management system meaning that you cannot sign messages or credentials with it after this operation. The DID will no longer be able to be resolved. This operation is not reversible.

Parameters

Name In Type Required Description
did path DID true Represents a specific DID that uniquely identifies the key resource.

200 Response

{
  "id": "928",
  "data": {
    "deleted": true
  }
}

Responses

Status Meaning Description Schema
200 OK The request was successful and will remove the DID. JobId
401 Unauthorized The request was unsuccessful, because you don't own the DID. Error
404 Not Found The DID does not exist. Error
405 Method not Allowed The {did} value is blank/empty. Please ensure that the {did} value does exist. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

Export DID

POST /dids/{did}/export REQUEST

curl --location --request POST https://api.dock.io/dids/{did}/export \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "password": "aStr0ngP@ssw0rd"
    }'

Exports the DID document and keys as an encrypted Universal Wallet JSON-LD document

Parameters

Name In Type Required Description
did path DID true Represents a specific DID that uniquely identifies the key resource.
password body string true A password to encrypt the JSON-LD payload with

200 Response

{
}

Responses

Status Meaning Description Schema
200 OK The request was successful and the DID has been exported.
401 Unauthorized The request was unsuccessful, because you don't own the DID. Error
404 Not Found The DID does not exist. Error

Profiles

Endpoints

Organization Profiles are used to provide more context for an Issuer DID. Details about the issuer such as name and logo can be added using a Organization Profile. These details will be included in credentials that are issued by the DID.

Create Profile

POST /profiles REQUEST

curl --location --request POST 'https://api.dock.io/profiles' \
--header 'DOCK-API-TOKEN: API_KEY' \
--data-raw '{
  "name": "My Test Profile",
  "did": "did:dock:xyz",
  "description": "Testing out the Organization Profiles API",
  "logo":"data:image/png;base64,SomeBase64EncodedImage=="
}'
{
  "did": "did:dock:xyz",
  "name": "My Test Profile",
  "description": "Testing out the Organization Profiles API",
  "logo":"data:image/png;base64,SomeBase64EncodedImage=="
}

The did and name fields are required to create a new Profile.

Parameters

Name In Type Required Description
did body DIDDock true DID as fully qualified, e.g., did:dock:.
name body string true The name to use for this issuer (e.g. a school name).
description body string false A description of the issuer.
logo body string false A Base64 encoded image to use as the logo for the issuer.

200 Response

{
  "did": "did:dock:xyz",
  "name": "My Test Profile",
  "description": "Testing out the Organization Profiles API",
  "logo":"data:image/png;base64,SomeBase64EncodedImage=="
}

Responses

Status Meaning Description Schema
200 OK The request was successful and the Profile was created.
400 Bad Request The request was unsuccessful, because of invalid params. Error

Get Profile

GET /profiles/{did} REQUEST

curl --location --request GET 'https://api.dock.io/profiles/did:dock:xyz' \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''

When a DID is provided in the path, the API will retrieve the Profile associated with that DID.

Parameters

Name In Type Required Description
did path DIDDock true Represents a specific DID that uniquely identifies the profile.

200 Response

{
  "did": "did:dock:xyz",
  "name": "My Test Profile",
  "description": "Testing out the Organization Profiles API",
  "logo":"data:image/png;base64,SomeBase64EncodedImage=="
}

Responses

Status Meaning Description Schema
200 OK The request was successful and will return the profile.
404 Not Found The requested profile was not found. Error

List Profiles

GET /profiles REQUEST

curl --location --request GET 'https://api.dock.io/profiles' \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''

Return a list of all Profiles that your user account controls.

200 Response

[
  {
    "did": "did:dock:xyz",
    "name": "My Test Profile",
    "description": "Testing out the Organization Profiles API",
    "logo":"data:image/png;base64,SomeBase64EncodedImage=="
  }
]

Parameters

Name In Type Required Description
offset query integer false How many items to offset by for pagination
limit query integer false How many items to return at one time (max 64)

Responses

Status Meaning Description Schema
200 OK All of a user's profiles. DIDDock

Update Profile

PATCH /profiles/{did} REQUEST

curl --location --request PATCH 'https://api.dock.io/profiles/did:dock:xyz' \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "did": "did:dock:xyz",
  "name": "My Test Profile",
  "description": "Testing out the Organization Profiles API",
  "logo":"data:image/png;base64,SomeBase64EncodedImage=="
}'

{
  "did": "did:dock:xyz",
  "name": "My Test Profile",
  "description": "Testing out the Organization Profiles API",
  "logo":"data:image/png;base64,SomeBase64EncodedImage=="
}

The update profile operation means that you can update the details of the profile. To do so, you need to provide a different value for at least one of name, description or logo.

Parameters

Name In Type Required Description
did body DIDDock true DID as fully qualified, e.g., did:dock:.
name body string true The name to use for this issuer (e.g. a school name).
description body string false A description of the issuer.
logo body string false A Base64 encoded image to use as the logo for the issuer.

200 Response

{
  "did": "did:dock:xyz",
  "name": "My Test Profile",
  "description": "Testing out the Organization Profiles API",
  "logo":"data:image/png;base64,SomeBase64EncodedImage=="
}

Responses

Status Meaning Description Schema
200 OK The request was successful and will update the profile.
400 Bad Request The controller value is incorrect. Error
401 Unauthorized The request was unsuccessful, because you don't own the profile. Error
404 Not Found The profile does not exist. Error

Delete Profile

DELETE /profiles/{did} REQUEST

curl --location --request DELETE https://api.dock.io/profiles/{did} \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    }'

Deletes a profile from our platform. It does NOT delete the associated DID, nor revoke the credentials issued for the profile.

Parameters

Name In Type Required Description
did path DID true Represents a specific DID that uniquely identifies the profile to delete.

200 Response

{
}

Responses

Status Meaning Description Schema
200 OK The request was successful and will remove the profile.
401 Unauthorized The request was unsuccessful because you don't own the profile. Error
404 Not Found The profile does not exist. Error
405 Method not Allowed The {did} value is blank/empty. Please ensure that the {did} value does exist. Error

Credentials

Endpoints

You can create and sign Verifiable Credentials on Dock Certs and its API. By default, Dock does not store the credential - only its metadata. You can choose to persist a credential, in which case we will encrypt and store the credential for later retrieval using a password. Verifiable Credentials are cryptographically secure and tamper-proof. Once issued, they cannot be edited.

The Dock API supports issuing two types of credentials. The native Dock Verifiable Credentials and Polygon ID Verifiable Credentials.

Issue Credential

POST /credentials REQUEST


{
  "anchor": true,
  "persist": false,
  "distribute": true,
  "recipientEmail": "myemail@dock.io",
  "schema": "https://schema.dock.io/TestSchema-V1-1695817897561.json",
  "template": "b8dd5768-0777-42c2-ae73-859e1079369b",
  "credential": {
    "type": ["UniversityDegreeCredential"],
    "subject": {
      "id": "did:dock:5CDsD8HZa6TeSfgmMcxAkbSXYWeob4jFQmtU6sxr4XWTZzUA",
      "degree": {
        "type": "BachelorDegree",
        "name": "Bachelor of Science and Arts"
      }
    },
    "issuer": "did:dock:xyz",
    "issuanceDate": "2020-08-24T14:15:22Z"
  }
}
curl --location --request POST https://api.dock.io/credentials/ \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "persist": false,
  "anchor": true,
  "template": "b8dd5768-0777-42c2-ae73-859e1079369b",
  "credential": {
    "type": ["UniversityDegreeCredential"],
    "subject": {
      "id": "did:dock:5CDsD8HZa6TeSfgmMcxAkbSXYWeob4jFQmtU6sxr4XWTZzUA",
      "degree": {
        "type": "BachelorDegree",
        "name": "Bachelor of Science and Arts"
      }
    },
    "issuer": "did:dock:xyz",
    "issuanceDate": "2020-08-24T14:15:22Z"
  }
}'


Creates and issues a JSON-LD Verifiable Credential that conforms to the W3C VCDM specification. The type values and subject properties must be represented by a schema URI in the context property. If you do not specify a context property, the API will automatically generate an embedded JSON-LD context based on the properties within your credential. You can read more about JSON-LD and contexts here.

To sign a credential, an issuer must be supplied as either a fully qualified DID string or an object with at least an id property which is a fully qualified DID. (e.g: did:dock:xyz)

By default, Dock does not store the credential contents at all - only minimal credential metadata. You can choose to set the persist value to true and provide a password string which will store the credential contents encrypted on our platform. The following metadata is stored on each issuance:

For a detailed example of the credential workflow. Please refer here.

Zero Knowledge Proofs (ZKP)

Dock credentials support anonymous credentials using Zero Knowledge Proofs and Selective Disclosure by using the BBS+ signing algorithm when issuing the credential. To enable this functionality, simply set the algorithm field in the request to dockbbs+.

Credential Distribution

Dock's API has built in credential distribution on issuance, allowing you to send credentials directly to a holder's email and/or Dock-compatible wallet. You can achieve this by supplying the recipientEmail field and distribute: true in your request. For DID distribution, simply set the credentialSubject.id property to the holder's DID.

Revocation

In order to support revocation the credential must be linked to a revocation registry at the time of issuance. To link the revocation registry to the credential set the status field in the Credential body to the registry.id value.

Parameters

Name In Type Required Description
anchor body boolean false Whether to anchor the credential on the blockchain as soon as it is issued. Defaults to false.
persist body boolean false Whether to store an encrypted version of this credential with us. Defaults to false, if true you must supply password.
password body string false Password used to encrypt the credential if you choose to store it. The same password must be used to retrieve the credential contents. Dock does not store this password.
template body UUID string false The ID of the intended template/design, optional
format body string false Specifies the output format of the credential, either jsonld or jwt. Defaults to jsonld.
algorithm body string false Specifies which signing algorithm to use to sign the issued credential. Defaults to ed25519.
distribute body boolean false Whether to use credential distribution to DID/email, optional
recipientEmail body string false The holder's email for email distribution
credential body Credential true Credential object as described in the schema.

Enumerated Values

Parameter Value Description
algorithm ed25519 or secp256k1 or sr25519 or dockbbs+ The algorithm used to sign the credential.

200 Response

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "https://creds.dock.io/f087cbfabc90f8b996971ba47598e82b1a03523cb9460217ad58a819cd9c09eb",
  "type": [
    "VerifiableCredential",
    "UniversityDegreeCredential"
  ],
  "credentialSubject": {
    "id": "did:dock:5CDsD8HZa6TeSfgmMcxAkbSXYWeob4jFQmtU6sxr4XWTZzUA",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science and Arts"
    }
  },
  "issuanceDate": "2020-08-24T14:15:22Z",
  "proof": {
    "type": "EcdsaSecp256k1Signature2019",
    "created": "2021-11-22T22:51:08Z",
    "verificationMethod": "did:dock:5FfmGmkY1BqEqRQhRLCLDLHPBFvhSbEBK3DJhEk9mbkpfAXT#keys-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "zAN1rKrjNqYSr6mjbNEohqhCAnEoLWFgJutBmYMkXZYG8RatBuCv7ymFHEchufa1vjiM4JkHCkasswjukYVVJT3rBmTaRaUDHT"
  },
  "issuer": "did:dock:xyz"
}

Responses

Status Meaning Description Schema
200 OK The request was successful and returns the created Verifiable Credential. VerifiableCredential
400 Bad Request The request was unsuccessful, because of invalid/insufficient credential params. Error
401 Unauthorized The request was unsuccessful, either because the authorization token was missing/invalid or you don't own the DID. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

Request Claims

POST /credentials/request-claims REQUEST


{
  "schema": "https://docknetwork.github.io/vc-schemas/basic-credential.json",
  "claims": [
    "id"
  ],
  "credentialOptions": {
    "anchor": false,
    "persist": false,
    "credential": {
      "schema": "https://docknetwork.github.io/vc-schemas/basic-credential.json",
      "name": "Basic Credential",
      "type": [
        "VerifiableCredential",
        "BasicCredential"
      ],
      "issuer": "did:dock:5GZn9zQTggPWijzgnoV8sZ5a74rFqC8qrz2ncp7GggeGCtKd",
      "issuanceDate": "2023-12-20T00:33:15.803Z",
      "subject": {
        "name": "Predefined Claim"
      }
    },
    "distribute": false
  }
}
curl --location --request POST https://api.dock.io/credentials/ \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "schema": "https://docknetwork.github.io/vc-schemas/basic-credential.json",
  "claims": [
    "id"
  ],
  "credentialOptions": {
    "anchor": false,
    "persist": false,
    "credential": {
      "schema": "https://docknetwork.github.io/vc-schemas/basic-credential.json",
      "name": "Basic Credential",
      "type": [
        "VerifiableCredential",
        "BasicCredential"
      ],
      "issuer": "did:dock:5GZn9zQTggPWijzgnoV8sZ5a74rFqC8qrz2ncp7GggeGCtKd",
      "issuanceDate": "2023-12-20T00:33:15.803Z",
      "subject": {
        "name": "Predefined Claim"
      }
    },
    "distribute": false
  }
}'

Creates a request to gather certain claims and then issues the holder a credential after submission. The claims are user provided and type is based on the schema provided. This can be useful to catch a subject's DID without knowing it beforehand, name or other field. It should only be used when you do not already know this data or cannot find it by other means. There is a risk that a user may enter false data - so use it sparingly and not for fields that are important.

Typically, once the request has been created, you would show the holder the QR URL as an image or deep link for them to scan with a wallet and enter claims.

Parameters

Name In Type Required Description
schema body string false Schema URL for the issued credential
claims body array false The list of claims for the subject
credentialOptions body CredentialIssueParameters true Credential issue parameters.

200 Response

{
  "id": "f1831768-853f-4ac1-ae99-adf61a92724f",
  "qrUrl": "openid://discovery?issuer=https://api.dock.io/openid/connect/issuers/f1831768-853f-4ac1-ae99-adf61a92724f",
  "created": "2023-12-20T00:33:35.720Z",
  "updated": "2023-12-20T00:33:35.720Z",
  "singleUse": true,
  "claimMap": {
    "id": "id"
  },
  "issuer": "did:dock:5GZn9zQTggPWijzgnoV8sZ5a74rFqC8qrz2ncp7GggeGCtKd",
  "protocol": "openid",
  "credentialOptions": {
    "anchor": false,
    "persist": false,
    "credential": {
      "name": "Basic Credential",
      "type": [
        "VerifiableCredential",
        "BasicCredential"
      ],
      "issuer": "did:dock:5GZn9zQTggPWijzgnoV8sZ5a74rFqC8qrz2ncp7GggeGCtKd",
      "schema": "https://docknetwork.github.io/vc-schemas/basic-credential.json",
      "subject": {
        "name": "Predefined Claim"
      },
      "issuanceDate": "2023-12-20T00:33:15.803Z"
    },
    "distribute": false
  }
}

Responses

Status Meaning Description Schema
200 OK The request was successful and returns the claims request properties. OIDCIssuer
400 Bad Request The request was unsuccessful, because of invalid/insufficient credential params. Error
401 Unauthorized The request was unsuccessful, either because the authorization token was missing/invalid or you don't own the DID. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

Get Credential

GET /credentials/{id} REQUEST

curl --location --request GET 'https://api.dock.io/credentials/credential_id?password=test' \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''

When a credential has been persisted on our systems, you can fetch the credential data by supplying a credential ID and the password used at issuance to encrypt the credential.

Parameters

Name In Type Required Description
did path string true The ID of the credential (as a full URI).
password query string true The password given at issuance to encrypt the credential in storage

200 Response

{
  "id": "https://creds.dock.io/f087cbfabc90f8b996971ba47598e82b1a03523cb9460217ad58a819cd9c09eb",
  "byteSize": 1074,
  "issuerKey": "did:dock:5CU97DhQ3mnbxPAiYw3GoRqFcnvCLGuHj3MS8evD8sARmg3e#KWAtkADdAy1rCiysr4cPZre4Lj7GFWGqyN5mP5X8xuzAnGzAb                     ",
  "createdAt": "2021-12-21T01:36:23.062Z",
  "credential": { ... }
}

Responses

Status Meaning Description Schema
200 OK The request was successful and will return the credential metadata and its JSON contents.
404 Not Found The requested credential was not found. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

Delete Credential

DELETE /credentials/{id} REQUEST

curl --location --request DELETE https://api.dock.io/credentials/{id} \
  --header 'DOCK-API-TOKEN: API_KEY'

A credential can have its metadata deleted, and if persisted the contents will also be deleted. Deleting a credential will remove any reference to it and its contents from our systems. This action cannot be undone. This action will not revoke or invalidate the credential in any way.

Parameters

Name In Type Required Description
did path string true The ID of the credential (as a full URL-encoded URI).

200 Response

{ }

Responses

Status Meaning Description Schema
200 OK The request was successful and credential will be deleted.
404 Not Found The request was unsuccessful, because the credential was not found. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

Get Credentials Metadata

GET /credentials REQUEST

curl --location --request GET 'https://api.dock.io/credentials' \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''

When you issue a credential with us, persistent or not, we will store certain metadata about the credential to make it easier for you to reference. You can pull a list of credential metadata using this route. To return the content of a persisted credential, you should use the GET /credentials/{id} route

Parameters

Name In Type Required Description
offset query integer false How many items to offset by for pagination
limit query integer false How many items to return at one time (max 64)

200 Response

[
  {
    "id": "https://creds.dock.io/6d601b80d56f4bb2f35b4fbe2406cc186a25b615a66fc405283ad5967f28c143",
    "issuerKey": "did:dock:xyz#xyz",
    "type": "BasicCredential",
    "revoked": false,
    "revocationRegistry": "rev-reg:dock:0x357c104d14e81d66ef43debee91eb62aac9af27c34a1e1a2194ee443989c4d44",
    "createdAt": "2022-04-18T18:28:09.914Z",
    "expirationDate": null,
    "byteSize": 917,
    "persist": false
  }
]

Responses

Status Meaning Description Schema
200 OK The request was successful and will return the credential metadata and its JSON contents.

Presentations

The presentation is signed using the holder's private key as it is being created. To validate the presentation, the verifier must also check the issuer's signature and the holder's public key. One way to achieve this is to make the holder have a DID too, so that the verifier can look up the DID on the chain and learn the public key.

The API allows you to create and sign a verifiable presentation out of one or more Verifiable Credentials.

For a detailed example of the presentations workflow. Please refer here.

Create Presentation

POST /presentations REQUEST

curl --location --request POST https://api.dock.io/presentations/ \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "holder": "did:dock:xyz",
  "challenge": "string",
  "domain": "string",
  "credentials": [
    {
      "@context": [
        "string"
      ],
      "id": "https://creds.dock.io/f087cbfabc90f8b996971ba47598e82b1a03523cb9460217ad58a819cd9c09eb",
      "type": [
        "string"
      ],
      "credentialSubject": {},
      "issuer": "did:dock:xyz",
      "issuanceDate": "2019-08-24T14:15:22Z",
      "expirationDate": "2019-08-24T14:15:22Z",
      "credentialStatus": {},
      "proof": {
        "type": "Sr25519Signature2020",
        "proofPurpose": "assertionMethod",
        "verificationMethod": "string",
        "created": "2019-08-24T14:15:22Z",
        "proofValue": "string"
      }
    }
  ]
}'


{
  "holder": "did:dock:xyz",
  "challenge": "string",
  "domain": "string",
  "credentials": [
    {
      "@context": [
        "string"
      ],
      "id": "https://creds.dock.io/f087cbfabc90f8b996971ba47598e82b1a03523cb9460217ad58a819cd9c09eb",
      "type": [
        "string"
      ],
      "credentialSubject": {},
      "issuer": "did:dock:xyz",
      "issuanceDate": "2019-08-24T14:15:22Z",
      "expirationDate": "2019-08-24T14:15:22Z",
      "credentialStatus": {},
      "proof": {
        "type": "Sr25519Signature2020",
        "proofPurpose": "assertionMethod",
        "verificationMethod": "string",
        "created": "2019-08-24T14:15:22Z",
        "proofValue": "string"
      }
    }
  ]
}

The holder while creating the presentation signs it with his private key. For the verifier to verify the presentation, in addition to verifying the issuer's signature, he/she needs to verify this signature as well, and for that he must know the holder's public key.

This is an operation to create and sign a verifiable presentation out of one or more Verifiable Credentials.

Parameters

Name In Type Required Description
holder body DIDDock true DID as fully qualified, e.g., did:dock:xyz.
challenge body string false Presentation's Challenge in a string format. The default value for this is random hex string. NOTE: if this presentation is being created to respond to a proof-request the challenge should be set to the value from the nonce field in the proof-request.
domain body string false A domain for the proof in a string format. The default value for the domain is dock.io.
credentials body VerifiableCredential false Verifiable (signed) Credential returned by API.

Enumerated Values

Parameter Value Description
type Sr25519Signature2020 or Ed25519Signature2018 or EcdsaSecp256k1Signature2019 Type of Signature.
proofPurpose assertionMethod or authentication The purpose the credential will be used for.

200 Response

{

  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
  "type": ["VerifiablePresentation", "CredentialManagerPresentation"],
  "verifiableCredential": [{  }],
  "proof": [{  }]
}

Responses

Status Meaning Description Schema
200 OK The request was successful and returns a Verifiable Presentation. VerifiablePresentation
400 Bad Request The request was unsuccessful, because of invalid/insufficient parameters. Error
401 Unauthorized The request was unsuccessful, either because of a missing/invalid auth header or you don't own the DID. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

Create Proof Request

POST /proof-requests REQUEST

curl --location --request POST https://api.dock.io/proof-requests/ \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Proof Request Test",
    "purpose": "Prove income",
    "request": {
        "input_descriptors": [
            {
                "id": "ProofIncome-1",
                "name": "Proof Request Test",
                "purpose": "Prove income",
                "constraints": {
                    "fields": [
                        {
                            "path": [
                                "$.credentialSubject.id",
                                "$.credentialSubject.income.total"
                            ]
                        }
                    ]
                }
          ]
    }
    }'

{
    "name": "Proof Request Test",
    "purpose": "Prove income",
    "request": {
        "input_descriptors": [
            {
                "id": "ProofIncome-1",
                "name": "Proof Request Test",
                "purpose": "Prove income",
                "constraints": {
                    "fields": [
                        {
                            "path": [
                                "$.credentialSubject.id",
                                "$.credentialSubject.income.total"
                            ]
                        }
                    ]
                }
          ]
    }
    }

It often makes sense for a verifier to request proof of credentials from a holder. For this, we have built a proof requests system into the API that works with the Dock Wallet. When a request is created, you will receive a URL which you should display in a QR code for a wallet application to scan. You can define which attributes should exist in the credential, a name for the holder and yourself to see and a nonce/challenge which prevents replay attacks.

Our system supports the DIF Presentation Exchange (PEX) syntax for querying and filtering credentials.

See the https://identity.foundation/presentation-exchange/#input-descriptor-extensions for more examples, but a few common use cases are:

Require a numeric attribute to be within a range

For example, a verifier might require that the holder have an income between $100,000 and $200,000 per year. This could be requested using the following input_descriptor

{
  path: ['$.credentialSubject.income.2022.total'],
  filter: {
    type: 'number',
    minimum: 100000,
    maximum: 200000
  },
}

Require a date attribute to be within a range

For example, a verifier might require that the credential be issued after a certain date. In this example the verifier is requiring that the credential was issued between January 1, 2020 and December 31, 2020.

{
  path: ['$.issuanceDate'],
  filter: {
    "type": "string",
    "format": "date",
    "formatMinimum": "2020-01-01",
    "formatMaximum": "2020-12-31"
  },
}

Parameters

Name In Type Required Description
attributes body object false Requested attribute specifications of proof request
name body string false Proof request name, will be shown to the holder
nonce body string false Nonce or challenge for the presentation to match

200 Response

{
  "id": "aeec1776-84c3-4783-b80b-c6690a652892",
  "name": "Proof Request Test",
  "nonce": "1234567890",
  "verified": false,
  "created": "2022-10-17T22:48:30.619Z",
  "updated": "2022-10-17T22:48:30.619Z",
  "presentation": {},
  "response_url": "https://api.dock.io/proof-requests/aeec1776-84c3-4783-b80b-c6690a652892/send-presentation",
  "type": "proof-request",
    "qr": "https://creds-testnet.dock.io/proof/acaae15e-3c6e-412e-951e-4dc129b9745a",
  "request": {
        "input_descriptors": [
            {
                "id": "ProofIncome-1",
                "constraints": {
                    "fields": [
                        {
                            "path": [
                                "$.credentialSubject.income.total"
                            ],
              "filter": {
                "type": "number",
                "minimum": 100000,
                "maximum": 200000
              }
                        }
                    ]
                }
            }
        ]
    }
}

Responses

Status Meaning Description Schema
200 OK The request was successful and returns a Verifiable Presentation. VerifiablePresentation
400 Bad Request The request was unsuccessful, because of invalid/insufficient parameters. Error
401 Unauthorized The request was unsuccessful, either because of a missing/invalid auth header or you don't own the DID. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

List Proof Requests

GET /proof-requests REQUEST

curl --location --request GET https://api.dock.io/proof-requests/ \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw'{

  }'

Return a list of all proof requests and their verification status

200 Response

[
  {
        "id": "f2ea3225-ef6b-44d7-a37c-7713c66875b5",
        "name": "Proof of Bachelors of Education",
        "nonce": "6684fb3d878f2c3a25e35e36045bde8d",
        "verified": false,
        "created": "2023-04-05T22:00:25.729Z",
        "updated": "2023-04-05T22:00:25.729Z",
        "presentation": {},
        "response_url": "https://api-testnet.dock.io/proof-requests/f2ea3225-ef6b-44d7-a37c-7713c66875b5/send-presentation",
        "type": "proof-request",
        "qr": "https://creds-testnet.dock.io/proof/f2ea3225-ef6b-44d7-a37c-7713c66875b5",
        "request": {
            "input_descriptors": [
                {
                    "id": "Credential 1",
                    "name": "Proof of Bachelors of Education",
                    "purpose": "Prove that the holder has a Bachelors of Education degree",
                    "constraints": {
                        "fields": [
                            {
                                "path": [
                                    "$.credentialSubject.degreeName",
                                    "$.credentialSubject.degreeType",
                                    "$.credentialSubject.dateEarned | date: \"%B %d, %Y\"",
                                    "$.credentialSubject.fullName"
                                ]
                            },
                            {
                                "path": [
                                    "$.name"
                                ],
                                "filter": {
                                    "type": "string",
                                    "pattern": "Bachelors of Education"
                                }
                            }
                        ]
                    }
                }
            ]
        }
    }
]

Parameters

Name In Type Required Description
offset query integer false How many items to offset by for pagination
limit query integer false How many items to return at one time (max 64)

Responses

Status Meaning Description Schema
200 OK The request was successful and will return all proof requests created by the user. Inline

Get Proof Request

GET /proof-requests/{id} REQUEST

curl --location --request GET https://api.dock.io/proof-requests/{id} \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''


Get the details of an existing proof request and its verification status

Parameters

Name In Type Required Description
id path UUID true Proof request UUID

200 Response

{
    "qr": "https://creds-testnet.dock.io/proof/acaae15e-3c6e-412e-951e-4dc129b9745a",
    "id": "fcaae15e-3c6e-412e-951e-4dc129b9745a",
    "name": "Proof Request Test",
    "nonce": "ffa6d005dfd8ddecf1664079bda1af1e",
    "created": "2023-05-16T15:42:53.925Z",
    "updated": "2023-05-16T15:42:53.925Z",
    "verified": false,
    "response_url": "https://api-testnet.dock.io/proof-requests/acaae15e-3c6e-412e-951e-4dc129b9745a/send-presentation",
    "request": {
        "id": "acaae15e-3c6e-412e-951e-4dc129b9745a",
        "input_descriptors": [
            {
                "id": "ProofIncome-1",
                "constraints": {
                    "fields": [
                        {
                            "path": [
                                "$.credentialSubject.id",
                                "$.credentialSubject.income.total"
                            ]
                        }
                    ]
                }
            }
        ]
    },
    "type": "proof-request"
}

Responses

Status Meaning Description Schema
200 OK The request was successful and will return the proof request. Registry
404 Not Found The request was unsuccessful, because the proof request was not found. Error

List Proof Request Templates

GET /proof-templates REQUEST

When working with Proof Requests you will often want to request the same information from holders. To make this easier you can create Proof Request Templates to define the contents of the proof requests to be re-used.

Code samples

# You can also use wget
curl -X GET https://api-testnet.dock.io/proof-templates \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Parameters

Name In Type Required Description
offset query integer(int32) false How many items to offset by for pagination
limit query integer(int32) false How many items to return at one time (max 64)

Example responses

200 Response

[
  {
        "id": "dcd6e820-5ea6-4835-8ad5-ddf3de82f3d2",
        "name": "Test Proof Template",
        "created": "2023-05-09T13:18:09.290Z",
        "updated": "2023-05-09T13:18:09.290Z",
        "request": {
            "input_descriptors": [
                {
                    "id": "Credential 1",
                    "name": "Test Proof Template",
                    "purpose": "University Degree with name, issued date requested",
                    "constraints": {
                        "fields": [
                            {
                                "path": [
                                    "$.credentialSubject.name",
                                    "$.issuanceDate"
                                ]
                            },
                            {
                                "path": [
                                    "$.type[*]"
                                ],
                                "filter": {
                                    "type": "string",
                                    "pattern": "UniversityDegree"
                                }
                            }
                        ]
                    }
                }
            ]
        }
    }
]

Responses

Status Meaning Description Schema
200 OK A paged array of proof templates ProofRequests

Create Proof Request Template

POST /proof-templates REQUEST

Code samples

# You can also use wget
curl -X POST https://api-testnet.dock.io/proof-templates \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Body parameter

{
  "attributes": {
    "property1": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    },
    "property2": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    }
  },
  "name": "Proof request",
  "nonce": "1234567890",
  "qr": "string"
}

Parameters

Name In Type Required Description
body body ProofRequest true Proof template object

Example responses

200 Response

{
  "attributes": {
    "property1": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    },
    "property2": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    }
  },
  "name": "Proof request",
  "nonce": "1234567890",
  "qr": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "error": "string",
  "created": "2019-08-24T14:15:22Z",
  "updated": "2019-08-24T14:15:22Z"
}

Responses

Status Meaning Description Schema
200 OK Proof request template created ProofTemplateObject
400 Bad Request Invalid parameters Error
402 Payment Required Transaction limit reached or upgrade required to proceed Error

Get Proof Template History

GET /proof-templates/{id}/history REQUEST

Get all of the previously created proof requests based on the specified template.

Code samples

# You can also use wget
curl -X GET https://api-testnet.dock.io/proof-templates/{id}/history \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Parameters

Name In Type Required Description
id path string(uuid) true Proof template UUID
offset query integer(int32) false How many items to offset by for pagination
limit query integer(int32) false How many items to return at one time (max 64)

Example responses

200 Response

[
  {
    "attributes": {
      "property1": {
        "name": "favouriteDrink",
        "names": [
          "age"
        ]
      },
      "property2": {
        "name": "favouriteDrink",
        "names": [
          "age"
        ]
      }
    },
    "name": "Proof request",
    "nonce": "1234567890",
    "qr": "string"
  }
]

Responses

Status Meaning Description Schema
200 OK Returns the information about the proof request history ProofRequests
404 Not Found Proof template was not found. Error

Create Proof Request from a Template

POST /proof-templates/{id}/request REQUEST

Create a proof requtest based on the specified template.

Code samples

# You can also use wget
curl -X POST https://api-testnet.dock.io/proof-templates/{id}/request \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Body parameter

{
  "nonce": "string",
  "domain": "string"
}

Parameters

Name In Type Required Description
body body object true Specify optional nonce and domain
» nonce body string false none
» domain body string false none
id path string(uuid) true Proof template UUID

Example responses

200 Response

{
  "attributes": {
    "property1": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    },
    "property2": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    }
  },
  "name": "Proof request",
  "nonce": "1234567890",
  "qr": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "error": "string",
  "response_url": "string",
  "verified": true,
  "presentation": {},
  "created": "2019-08-24T14:15:22Z",
  "updated": "2019-08-24T14:15:22Z"
}

Responses

Status Meaning Description Schema
200 OK Returns the information about the proof request ProofRequestObject
402 Payment Required Transaction limit reached or upgrade required to proceed Error
404 Not Found Proof template was not found. Error

Get Proof Template

GET /proof-templates/{id} REQUEST

Get the details about a specific template.

Code samples

# You can also use wget
curl -X GET https://api-testnet.dock.io/proof-templates/{id} \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Parameters

Name In Type Required Description
id path string(uuid) true Proof template UUID

Example responses

200 Response

{
  "attributes": {
    "property1": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    },
    "property2": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    }
  },
  "name": "Proof request",
  "nonce": "1234567890",
  "qr": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "error": "string",
  "created": "2019-08-24T14:15:22Z",
  "updated": "2019-08-24T14:15:22Z"
}

Responses

Status Meaning Description Schema
200 OK Returns the information about the proof templates ProofTemplateObject
404 Not Found Proof templates was not found. Error

Update Proof Template

PATCH /proof-templates/{id} REQUEST

Code samples

# You can also use wget
curl -X PATCH https://api-testnet.dock.io/proof-templates/{id} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Body parameter

{
  "attributes": {
    "property1": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    },
    "property2": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    }
  },
  "name": "Proof request",
  "nonce": "1234567890",
  "qr": "string"
}

Parameters

Name In Type Required Description
body body ProofRequest true Proof template object
id path string(uuid) true Proof template UUID

Example responses

200 Response

{
  "attributes": {
    "property1": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    },
    "property2": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    }
  },
  "name": "Proof request",
  "nonce": "1234567890",
  "qr": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "error": "string",
  "created": "2019-08-24T14:15:22Z",
  "updated": "2019-08-24T14:15:22Z"
}

Responses

Status Meaning Description Schema
200 OK Profile has been updated ProofTemplateObject
400 Bad Request Error creating profile Error
402 Payment Required Transaction limit reached or upgrade required to proceed Error
404 Not Found Proof templates was not found. Error

Delete Proof Template

DELETE /proof-templates/{id} REQUEST

Deletes the specified template and any associated data.

Code samples

# You can also use wget
curl -X DELETE https://api-testnet.dock.io/proof-templates/{id} \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Parameters

Name In Type Required Description
id path string(uuid) true Proof template UUID

Example responses

400 Response

{
  "status": 0,
  "type": "string",
  "message": "string"
}

Responses

Status Meaning Description Schema
200 OK Proof templates will be deleted None
400 Bad Request Something went wrong. Error
404 Not Found Proof templates was not found. Error

Registries

Endpoints

Revocation means deleting or updating a credential. On Dock, credential revocation is managed with a revocation registry.

There can be multiple registries on the chain, and each registry has a unique id. It is recommended that the revocation authority create a new registry for each credential type. Dock Certs allows you to create, delete, and revoke/unrevoke the credential. You can retrieve a specified registry as well as a list of all registries created by the user.

For a detailed example of the registry workflow. Please refer here.

Create Registry

POST /registries REQUEST

curl --location --request POST https://api.dock.io/registries/ \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "addOnly": true,
  "policy": [
    "did:dock:xyz"
  ],
  "type": "CredentialStatusList2017"
}'



{
  "addOnly": true,
  "policy": [
    "did:dock:xyz"
  ],
  "type": "CredentialStatusList2017"
}

To create a registry, you have to create a policy object for which a DID is needed. It is advised that the DID is registered on the chain first. Otherwise, someone can look at the registry and register the DID, thus gaining control of the registry.

Choosing the right revocation registry is essential. Here's a simplified overview of the available options: - CredentialStatusList2017 - Only supports non-BBS+ credentials. - Individual Tracking: Each entry is tracked separately, which means more ledger space is used for multiple entries. - This registry is cost-effective for a single entry. However, managing several entries can be more expensive. - Implements add-only policies. - StatusList2021Entry - Only supports non-BBS+ credentials. - Recommended for most users. - Collective Tracking: Manages all revocation entries together, making it less costly to revoke multiple credentials simultaneously. - W3C Compliant. - DockVBAccumulator2022 - Only supports BBS+ credentials. - Utilizes an on-ledger accumulator for enhanced privacy. - Offers more privacy than the W3C Status List 2021.

Parameters

Name In Type Required Description
addOnly body boolean false True/false options. The default value is "false".
policy body [DIDDock] true The DIDs which control this registry. You must own a DID listed here to use the registry. Only one policy supported as of now: OneOf DID in list.
type body string false Specifies which type of registry to create. Defaults to StatusList2021Entry.

Enumerated Values

Parameter Value Description
type StatusList2021Entry or CredentialStatusList2017 or DockVBAccumulator2022 The type used in registry creation.

200 Response

{
  "id": "930",
  "data": {
    "id": "6151e62d7e03bc4012fde0595cfdb0d140e463a2f0ad5a431ff47243374bc612",
    "policy": {
      "type": "OneOf",
      "policy": [
        "did:dock:5GKeTJ7iMU4hEUwhK9a6ogh1bsWAv8Z1TMKnUf1vCNgdoiEM"
      ],
      "addOnly": false
    },
    "type": "CredentialStatusList2017",
  }
}

Responses

Status Meaning Description Schema
200 OK The request was successful and will try to create the registry. JobStartedResult
400 Bad Request The request was unsuccessful, because of invalid params, e.g., policy not supported. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

List Registries

GET /registries REQUEST

curl --location --request GET https://api.dock.io/registries/ \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw'{

  }'

Return a list of all registries created by the user. The list is returned with the registry id and policy of the revocation registry.

200 Response

[
  {
    "id": "6151e62d7e03bc4012fde0595cfdb0d140e463a2f0ad5a431ff47243374bc612",
    "policy_and_type": {
      "type": "OneOf",
      "policy": [
        "did:dock:5GKeTJ7iMU4hEUwhK9a6ogh1bsWAv8Z1TMKnUf1vCNgdoiEM"
      ],
      "addOnly": false
    },
    "registry_type": "CredentialStatusList2017",
    "created_at": "2021-11-25T12:20:51.773Z"
  }
]

Parameters

Name In Type Required Description
offset query integer false How many items to offset by for pagination
limit query integer false How many items to return at one time (max 64)

Responses

Status Meaning Description Schema
200 OK The request was successful and will return all registries created by the user. Inline
402 Payment required Transaction limit reached or upgrade required to proceed Error

Get Registry

GET /registries/{id} REQUEST

curl --location --request GET https://api.dock.io/registries/{id} \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''


Get the details of an existing registry, such as policy, add-only status, when it was last updated, and controller(s). You need only supply the revocation registry id that was returned upon revocation registry creation.

Parameters

Name In Type Required Description
id path Hex32 true Revocation registry id.

200 Response

{
  "id": "6151e62d7e03bc4012fde0595cfdb0d140e463a2f0ad5a431ff47243374bc612",
  "policy_and_type": {
    "type": "OneOf",
    "policy": [
      "did:dock:5GKeTJ7iMU4hEUwhK9a6ogh1bsWAv8Z1TMKnUf1vCNgdoiEM"
    ],
    "addOnly": false
  },
  "registry_type": "CredentialStatusList2017",
  "created_at": "2021-11-25T12:20:51.773Z",
  "job_id": "930"
}

Responses

Status Meaning Description Schema
200 OK The request was successful and will return the revocation registry metadata. Registry
404 Not Found The request was unsuccessful, because the registry was not found. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

Revoke/Unrevoke Credential

POST /registries/{id} REQUEST

curl --location --request POST https://api.dock.io/registries/{id} \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "action": "revoke",
  "credentialIds": [
    "https://creds.dock.io/f087cbfabc90f8b996971ba47598e82b1a03523cb9460217ad58a819cd9c09eb"
  ]
}'


{
  "action": "revoke",
  "credentialIds": [
    "https://creds.dock.io/f087cbfabc90f8b996971ba47598e82b1a03523cb9460217ad58a819cd9c09eb"
  ]
}

Credential revocation is managed with on-chain revocation registries. To revoke a credential, its id (or hash of its id) must be added to the credential. It is advised to have one revocation registry per credential type. Revoking an already revoked credential has no effect.

Similar to the replay protection mechanism for DIDs, the last modified block number is kept for each registry, which is updated each time a credential is revoked or unrevoked. Unrevoking an unrevoked credential has no effect.

In this API, simply add Revoke/Unrevoke into the action parameter and input the desired credential ids.

Parameters

Name In Type Required Description
id path Hex32 true Revocation registry id.
action body string false The action taken, either revoke or unrevoke. The default value is "revoke"
credentialIds body array true The list of credential ids to act upon.

Enumerated Values

Parameter Value Description
action revoke or unrevoke Action to take on the registry.

200 Response

{
  "id": "931",
  "data": {
    "revokeIds": [
      "0xaff1aa6770d43d684690c0ad679a8608d5b7576feb3fdc1d6712decf73ca44ef"
    ]
  }
}

Responses

Status Meaning Description Schema
200 OK The request was successful and will try to revoke/unrevoke the credential. JobStartedResult
400 Bad Request The request was unsuccessful, because of invalid params. Error
404 Not Found The request was unsuccessful, because the registry was not found. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

Delete Registry

DELETE /registries/{id} REQUEST

curl --location --request POST https://api.dock.io/registries/{id} \
  --header 'DOCK-API-TOKEN: API_KEY'

A registry can be deleted, leading to all the corresponding revocation ids being deleted as well. This requires the signature from the owner, similar to the other updates.

Parameters

Name In Type Required Description
id path Hex32 true Revocation registry id.

200 Response

{
  "id": "932",
  "data": {
  "id": "6151e62d7e03bc4012fde0595cfdb0d140e463a2f0ad5a431ff47243374bc612",
  "hexId": "6151e62d7e03bc4012fde0595cfdb0d140e463a2f0ad5a431ff47243374bc612",
  "lastModified": 4226296
  }
}

Responses

Status Meaning Description Schema
200 OK The request was successful and revocation registry will be deleted. JobStartedResult
404 Not Found The request was unsuccessful, because the registry was not found. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

Revocation Status

Credentials can be revoked or unrevoked, and as such they contain a revocation status so that verifiers/issuers can check if the credential is still valid. Once a revocation registry has been created and credentials issued with it, you can check the revocation status. Verifiers will do this automatically.

Get Revocation Status

GET /revocationStatus/{regId}/{revId} REQUEST


curl --location --request GET https://api.dock.io/revocationStatus/{regId}/{revId} \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''

To check if an id is revoked or not, you can check its status with the registry id (regId) and revocation id (revId).

Parameters

Name In Type Required Description
regId path Hex32 true Revocation registry id.
revId path Hex32 true Credential revocation id.

200 Response

{
  "type": true
}

Responses

Status Meaning Description Schema
200 OK The request was successful and will return true, if the credential is revoked, false otherwise. Inline
404 Not Found The request was unsuccessful, because the registry was not found. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error
400 Server Error The request was unsuccessful, because you have not revoked or unrevoked the registered credential yet. Please try to revoke/unrevoke the registered credential and try again. Error

Get Revocation Status Witness

GET /revocationStatus/{regId}/{revId}/witness REQUEST


curl --location --request GET https://api.dock.io/revocationStatus/{regId}/{revId} \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''

The accumulator witness is utilized by the holder to generate a proof, which combines the witness with their revocation id associated with the credential id (revId) and the accumulator associated with the registry id (regId), allowing the verifier to validate the credential's status without directly accessing the revocation id on the blockchain.

Parameters

Name In Type Required Description
regId path Hex32 true Revocation registry id.
revId path Hex32 true Credential revocation id.

200 Response

{
  "value": "0x81aa308882b663491e2b42803ad0855b030d92a586bc378bc844e1e003c8098a23f0d7d75b4fdbfb4b42cfc42aca8ad3"
}

Responses

Status Meaning Description Schema
200 OK The request was successful and will return the membership witness. Inline
404 Not Found The request was unsuccessful, because the registry was not found. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error
400 Server Error The request was unsuccessful, because you have not revoked or unrevoked the registered credential yet. Please try to revoke/unrevoke the registered credential and try again. Error

Credential Schemas

Endpoints

Schemas are useful when enforcing a specific structure on a collection of data like a Verifiable Credential. Data Verification schemas, for example, are used to verify that the structure and contents of a Verifiable Credential conform to a published schema. On the other hand, Data Encoding schemas are used to map the contents of a Verifiable Credential to an alternative representation format, such as a binary format used in a zero-knowledge proof.

Create Schema

POST /schemas REQUEST

curl --location --request POST https://api.dock.io/schemas \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
 "$schema": "http://json-schema.org/draft-07/schema#",
 "description": "Dock Schema Example",
 "type": "object",
 "properties": {
  "id": {
    "type": "string"
 },
 "emailAddress": {
  "type": "string",
  "format": "email"
 },
 "alumniOf": {
  "type": "string"
 }
 },
 "required": [
  "emailAddress",
  "alumniOf"
 ],
 "additionalProperties": false,
 "author": "{{did}}"
}'


{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "Dock Schema Example",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "emailAddress": {
      "type": "string",
      "format": "email"
    },
    "alumniOf": {
      "type": "string"
    }
  },
  "required": [
    "emailAddress",
    "alumniOf"
  ],
  "additionalProperties": false,
  "author": "{{did}}"
}

Schemas are used to describe the structure of credentials, specifically the credential subject. It helps the issuer, holder, and verifier to unambiguously determine the claims contained within the credential. To create a schema, you need to define the object body using JSON schema.

Parameters

Name In Type Required Description
body body object true JSON-schema.

200 Response

{
  "id": "1082",
  "data": {
    "schema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "description": "Dock Schema Example 3",
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "emailAddress": {
          "type": "string",
          "format": "email"
        },
        "alumniOf": {
          "type": "string"
        }
      },
      "required": [
        "emailAddress",
        "alumniOf"
      ],
      "additionalProperties": false
    },
    "author": "did:dock:5FBZNTZ4eg2EBuvEcYdkEtAhCXhCEA8zmPzYTwexM3g13fkF",
    "signature": {
      "Secp256k1": "..."
    },
    "id": "https://schema.dock.io/TestSchema-V1-1695817897561.json",
    "uri": "https://schema.dock.io/TestSchema-V1-1695817897561.json"
  }
}

Responses

Status Meaning Description Schema
200 OK The request was successful and will try to create schema. JobId
400 Bad Request The request was unsuccessful, because of invalid params, e.g., size not supported or not JSON. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

List Schemas

GET /schemas REQUEST

curl --location --request GET https://api.dock.io/schemas \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''

Return a list of all schemas created by the authenticated user.

200 Response

[
  {
    "schema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "description": "Dock Schema Example",
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "emailAddress": {
          "type": "string",
          "format": "email"
        },
        "alumniOf": {
          "type": "string"
        }
      },
      "required": [
        "emailAddress",
        "alumniOf"
      ],
      "additionalProperties": false
    },
    "author": "did:dock:5HcbppP8LjoJFYRV7PTLEyPy3ZUK9JCkzC4PQHuVF34gRhe6",
    "id": "https://schema.dock.io/TestSchema-V1-1695817897561.json",
    "uri": "https://schema.dock.io/TestSchema-V1-1695817897561.json"
  }
]

Parameters

Name In Type Required Description
offset query integer false How many items to offset by for pagination
limit query integer false How many items to return at one time (max 64)

Responses

Status Meaning Description Schema
200 OK The request was successful and will return all schemas created by the user. Inline
402 Payment required Transaction limit reached or upgrade required to proceed Error

Get Schema

GET /schemas/{schemaId} REQUEST

curl --location --request GET https://api.dock.io/schemas/{schemaId} \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''

Reading a Schema from the Dock chain can easily be achieved by using the get method which will return the JSON schema to a specific schema ID. The schemaIdneeds to be URL encoded (e.g. /schemas/https%3A%2F%2Fschema.dock.io%2FTestSchema-V1-1695817897561.json)

Parameters

Name In Type Required Description
schemaId path String true A URL encoded schema id.

200 Response

{
  "schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "description": "Dock Schema Example",
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "emailAddress": {
        "type": "string",
        "format": "email"
      },
      "alumniOf": {
        "type": "string"
      }
    },
    "required": [
      "emailAddress",
      "alumniOf"
    ],
    "additionalProperties": false
  },
  "author": "did:dock:5HcbppP8LjoJFYRV7PTLEyPy3ZUK9JCkzC4PQHuVF34gRhe6",
  "id": "https://schema.dock.io/TestSchema-V1-1695817897561.json",
  "uri": "https://schema.dock.io/TestSchema-V1-1695817897561.json"
}

Responses

Status Meaning Description Schema
200 OK The request was successful and returns the requested Schema. Inline
404 Not Found The request was unsuccessful, because the schema was not found. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

Anchors

Endpoints

Anchoring allows users to store a digest of one or more credentials (or any document) on our blockchain, tying them to immutable timestamps and proving that they were generated at a certain moment in time. By enabling this feature, users will have more options for auditing credentials given and timestamping any documents.

The Dock Blockchain includes a module explicitly intended for proof of existence. You post the hash of a document on-chain at a specific block. Later you can use that hash to prove the document existed at or before that block.

The API allows you to create, get, and retrieve anchors as well as a list of all anchors created by the user.

For a detailed example of the anchor workflow. Please refer here.

Create Anchor

POST /anchors REQUEST

curl --location --request POST https://api.dock.io/anchors \

  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '[
  "can be a string",
  {
    "or": "a JSON document"
  }
]'


[
  "can be a string",
  {
    "or": "a JSON document"
  }
]

Creating an anchor will state on the blockchain that one or more document hashes were created at a specific time. In the context of verifiable credentials, anchors are used to attest that the credential document was not altered and was created at a specific time. Batching multiple documents/credentials into a single anchor is done through a Merkle tree and can save on cost/time as only the Merkle root has to be anchored.

The API will store the blake2b256 hash of a document or string that you provide. Dock provides a fully functioning reference client and SDK example for anchoring.

Parameters

Name In Type Required Description
body body array of strings or JSON true Supply an array of strings or JSON documents to be hashed and anchored to the blockchain. For credentials, send the Verifiable Credential document(s) or anchor when issuing.

200 Response

{
  "id": "829",
  "data": {
    "root": "0xdfc3cd9ff7836143746c292d4099e62277fac4c2b6a1c004d784adcbc0319634",
    "proofs": []
  }
}

Responses

Status Meaning Description Schema
200 OK The request was successful and will try to create an anchor on the blockchain. JobId
400 Bad Request The request was unsuccessful, because of invalid params. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

List Anchors

GET /anchors REQUEST

curl --location --request GET https://api.dock.io/anchors \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''

Return a list of all anchors created by the authenticated user, regardless of whether they have contributed to the batching or not.

200 Response

[
  {
    "anchor":"54bdd55207c4d41d2b8a7780e967bb5a06bdfb793fc4055baf244e60cd0d839c",
    "type": "single",
    "data": {
      "proofs": [],
      "root":"0x54bdd55207c4d41d2b8a7780e967bb5a06bdfb793fc4055baf244e60cd0d839c",
      "documentIds": [
        "https://creds.dock.io/credential/b1ed680d3d2d8167dc31bc4913e9c511"
      ]
     },
     "created_at": "2021-11-12T13:53:51.640Z",
     "job_id": "827"
  }
]

Parameters

Name In Type Required Description
offset query integer false How many items to offset by for pagination
limit query integer false How many items to return at one time (max 64)

Responses

Status Meaning Description Schema
200 OK The request was successful and will return all anchors created by the user. Inline
402 Payment required Transaction limit reached or upgrade required to proceed Error

Get Anchor

GET /anchors/{anchor} REQUEST

curl --location --request GET https://api.dock.io/anchors/{anchor} \
  --header 'DOCK-API-TOKEN: API_KEY'
  --data-raw ''

Get a specific anchor with the given ID.

Parameters

Name In Type Required Description
anchor path Hex32 true An anchor id.

200 Response

{
  "type": "single",
  "proofs": [],
  "root": "0x00",
  "created_at": "2021-11-30T15:47:24.667Z"
}

Responses

Status Meaning Description Schema
200 OK The request was successful and returns the anchor's details, e.g., blockHash and root. Anchor
404 Not Found The request was unsuccessful, because the anchor was not found. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

Verify Anchor

POST /verify REQUEST

curl --location --request POST https://api.dock.io/anchors \

  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '[
  "can be a string",
  {
    "or": "a JSON document"
  }
]'

{
  "documents": [],
  "proofs": [],
  "root": "0x00"
}

Verify an anchor's merkle root and proof by supplying the source documents (array of strings of JSON objects, same as in anchor creation).

Parameters

Name In Type Required Description
documents body array of strings or JSON true An array of strings or JSON objects to represent documents to be hashed
proofs body JSON object array true An array of proofs given on anchor creation
root body Hex32 true The anchor merkle root/ID.

200 Response

{
  "verified": true,
  "results": [
    {}
  ]
}

Responses

Status Meaning Description Schema
200 OK The request was successful and returns the anchor's details, e.g., blockHash and root. Anchor
402 Payment required Transaction limit reached or upgrade required to proceed Error

Jobs

Endpoints

In Dock Certs, "jobs" are blockchain transactions that we submit on your behalf. You can choose to either register a webhook or poll the API to receive job information. Certain things in the API, such as revoking a credential, require a blockchain transaction to finalize before the job can be considered "done". The time to wait varies on network load and other factors, but typically is within 5-10 seconds.

You can track the current job status by querying the job id returned as part of the initial API response that triggered the job. The work is done asynchronously.

Get Job Status and Data

GET /jobs/{Id} REQUEST

curl --location --request GET https://api.dock.io/jobs/{id} \
  --header 'DOCK-API-TOKEN: API_KEY'

To check the Job status and data, you can use the GET method and simply put the Job id. It will return information related to the job being processed and its associated blockchain transaction. On completion or failure, the job data will be updated with a response from the blockchain.

Parameters

Name In Type Required Description
id path JobId true Represents a Job id.

200 Response

{
  "id": "123",
  "result": {
    "InBlock": "0x00"
  },
  "status": "finalized"
}

Responses

Status Meaning Description Schema
200 OK The request was successful and return the job description. JobDesc
404 Not Found The request was unsuccessful, because the Job id was not found. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

Verify

VCDM Verification

POST /verify REQUEST

curl --location --request POST https://api.dock.io/verify \
  --header 'DOCK-API-TOKEN: API_KEY'
  --header 'Content-Type: application/json' \
  --data-raw '{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "https://creds.dock.io/credential/93a1cd57a46fd5e6e641f0288e2f8b44",
  "type": [
    "VerifiableCredential"
  ],
  "credentialSubject": [
    {
      "id": "did:dock:5Gwh4PxDjLUXnfqExALYTju9UpZTHzBLNb7j8Ug8NhTKivUe"
    }
  ],
  "issuanceDate": "2021-11-18T19:28:49.840Z",
  "proof": {
    "type": "EcdsaSecp256k1Signature2019",
    "created": "2021-11-18T19:28:51Z",
    "verificationMethod": "did:dock:5FfmGmkY1BqEqRQhRLCLDLHPBFvhSbEBK3DJhEk9mbkpfAXT#keys-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "zAN1rKvtics5d8AZ5rvm9n9DNjfXGtFegv48PorsWvQdeVKPkzSSyKJzdN3jjnfTNqFDg5FWpXeYhubsFKnX8zLNiBsb3D32k3"
  },
  "issuer": {
    "id": "did:dock:5FfmGmkY1BqEqRQhRLCLDLHPBFvhSbEBK3DJhEk9mbkpfAXT",
    "name": "my issuer"
  }
}'



{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "https://creds.dock.io/credential/93a1cd57a46fd5e6e641f0288e2f8b44",
  "type": [
    "VerifiableCredential"
  ],
  "credentialSubject": [
    {
      "id": "did:dock:5Gwh4PxDjLUXnfqExALYTju9UpZTHzBLNb7j8Ug8NhTKivUe"
    }
  ],
  "issuanceDate": "2021-11-18T19:28:49.840Z",
  "proof": {
    "type": "EcdsaSecp256k1Signature2019",
    "created": "2021-11-18T19:28:51Z",
    "verificationMethod": "did:dock:5FfmGmkY1BqEqRQhRLCLDLHPBFvhSbEBK3DJhEk9mbkpfAXT#keys-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "zAN1rKvtics5d8AZ5rvm9n9DNjfXGtFegv48PorsWvQdeVKPkzSSyKJzdN3jjnfTNqFDg5FWpXeYhubsFKnX8zLNiBsb3D32k3"
  },
  "issuer": {
    "id": "did:dock:5FfmGmkY1BqEqRQhRLCLDLHPBFvhSbEBK3DJhEk9mbkpfAXT",
    "name": "my issuer"
  }
}

A verifier upon receiving a verifiable presentation verifies the validity of each credential in the presentation. This includes checking the correctness of the data model of the credential, the authenticity by verifying the issuer's signature and revocation status if the credential is revocable. It then checks whether the presentation contains the signature from the holder on the presentation, including his given challenge.

You can verify issued/received credentials and presentations using this route. Verification will check that the JSON-LD document's cryptographic proof is correct and that it has not been revoked. It will return a verification status with a boolean verified result.

Parameters

Name In Type Required Description
body body VerifiableCredential or VerifiablePresentation true Provide as the body a Verifiable Credential or Verifiable Presentation JSON-LD document.

200 Response

{
  "verified": true,
  "results": [...]
}

Responses

Status Meaning Description Schema
200 OK The request was successful and will return the verification result. VerificationResponse
400 Bad Request The request was unsuccessful, because of invalid credential params. Error
402 Payment required Transaction limit reached or upgrade required to proceed Error

Sub-Accounts

Sub-accounts are a feature of the Dock Certs API that allows Dock enterprise customers to segregate their data within Dock's platform based on their own customers. Each sub-account can have its own keys, organization profiles, credential designs and verification templates conviently organized to help with tracking and auditing of the activity performed by each.

When using a sub-account the root account can set up separate API keys for each sub-account. By using the sub-account specific API key it will ensure all the transactions are attributed to that sub-account.

Sub-accounts diagram

Create Sub-Account

POST /subaccounts REQUEST


curl -X POST https://api-testnet.dock.io/subaccounts \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Body parameter

{
  "name": "string",
  "image": "string"
}

Parameters

Name In Type Required Description
body body object true Subaccount object
» name body string true The sub account name
» image body string false The sub account image

Example responses

200 Response

{
  "id": 0,
  "name": "string",
  "email": "string",
  "image": "string"
}

Responses

Status Meaning Description Schema
200 OK Subaccount has been created Subaccount
400 Bad Request Error creating subaccount Error
402 Payment Required Transaction limit reached or upgrade required to proceed Error

List Sub-Accounts

GET /subaccounts REQUEST

Code samples


curl -X GET https://api-testnet.dock.io/subaccounts \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Parameters

Name In Type Required Description
offset query integer(int32) false How many items to offset by for pagination
limit query integer(int32) false How many items to return at one time (max 64)

Example responses

200 Response

[
  {
    "id": 0,
    "name": "string",
    "email": "string",
    "image": "string"
  }
]

Responses

Status Meaning Description Schema
200 OK A paged array of subaccounts Subaccounts

Get Sub-Account by ID

GET /subaccounts/{id} REQUEST

Code samples


curl -X GET https://api-testnet.dock.io/subaccounts/{id} \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Parameters

Name In Type Required Description
id path string true An ID

Example responses

200 Response

{
  "id": 0,
  "name": "string",
  "email": "string",
  "image": "string"
}

Responses

Status Meaning Description Schema
200 OK Expected response to a valid request Subaccount
400 Bad Request Error getting subaccount Error
401 Unauthorized You do not own this subaccount Error
404 Not Found Subaccount was not found Error

PATCH /subaccounts/{id} REQUEST

Update the specified sub-account.

Code samples


curl -X PATCH https://api-testnet.dock.io/subaccounts/{id} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Body parameter

{
  "name": "string",
  "image": "string"
}

Parameters

Name In Type Required Description
id path string true An ID
body body object true Subaccount properties
» name body string true The sub account name
» image body string false The sub account image

Example responses

200 Response

{
  "id": 0,
  "name": "string",
  "email": "string",
  "image": "string"
}

Responses

Status Meaning Description Schema
200 OK Subaccount has been updated Subaccount
400 Bad Request Error creating subaccount Error
401 Unauthorized You do not own this subaccount Error
402 Payment Required Transaction limit reached or upgrade required to proceed Error

DELETE /subaccounts/{id} REQUEST

Deletes the specified sub-account.

Code samples


curl -X DELETE https://api-testnet.dock.io/subaccounts/{id} \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Parameters

Name In Type Required Description
id path string true An ID

Example responses

400 Response

{
  "status": 0,
  "type": "string",
  "message": "string"
}

Responses

Status Meaning Description Schema
200 OK Subaccount deleted None
400 Bad Request Error deleting subaccount Error
401 Unauthorized You do not own this subaccount Error
404 Not Found Subaccount was not found Error

Get Sub-Account Usage

GET /subaccounts/{id}/usage REQUEST

Get details about the activity that this sub-account has performed against the system.

Code samples


curl -X GET https://api-testnet.dock.io/subaccounts/{id}/usage \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Parameters

Name In Type Required Description
id path string true An ID
startTime query string(date-time) false Timestamp for the start of the range (ISO 8601)
endTime query string(date-time) false Timestamp for the end of the range (ISO 8601)
offset query integer(int32) false How many items to offset by for pagination
limit query integer(int32) false How many items to return at one time (max 64)

Example responses

200 Response

[
  {}
]

Responses

Status Meaning Description Schema
200 OK A paged array of subaccount transaction usage metadata ArrayResponse
401 Unauthorized You do not own this subaccount Error

Create Sub-Account API Key

POST /subaccounts/{id}/keys REQUEST

Creates an API key for a subaccount. In order for activity to be associated with the given sub-account an API key needs to be created for that sub-account and then that key must be used for all transactions related to that sub-account.

Code samples


curl -X POST https://api-testnet.dock.io/subaccounts/{id}/keys \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Body parameter

{}

Parameters

Name In Type Required Description
id path string true An ID
body body object false Subaccount properties

Example responses

200 Response

{
  "code": 0
}

Responses

Status Meaning Description Schema
200 OK Subaccount API key created Response
400 Bad Request Error creating subaccount API key Error
401 Unauthorized You do not own this subaccount Error
402 Payment Required Transaction limit reached or upgrade required to proceed Error

List Sub-Account API Keys

GET /subaccounts/{id}/keys REQUEST

Code samples


curl -X GET https://api-testnet.dock.io/subaccounts/{id}/keys \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Parameters

Name In Type Required Description
id path string true An ID
offset query integer(int32) false How many items to offset by for pagination
limit query integer(int32) false How many items to return at one time (max 64)

Example responses

200 Response

[
  {}
]

Responses

Status Meaning Description Schema
200 OK A paged array of subaccount key metadata ArrayResponse
401 Unauthorized You do not own this subaccount Error

Delete a Sub-Account API Key

DELETE /subaccounts/{id}/keys/{keyId} REQUEST

Delete the specified API key for the given sub-account.

Code samples


curl -X DELETE https://api-testnet.dock.io/subaccounts/{id}/keys/{keyId} \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Parameters

Name In Type Required Description
id path string true An ID
keyId path string true An API key ID

Example responses

400 Response

{
  "status": 0,
  "type": "string",
  "message": "string"
}

Responses

Status Meaning Description Schema
200 OK Subaccount API key deleted None
400 Bad Request Error deleting subaccount API key Error
401 Unauthorized You do not own this subaccount Error
404 Not Found Subaccount API key was not found Error

Messaging

Operations about DIDComm messaging. DIDComm messages are addressed by DID using Dock's relay service.

The current most common use case for the messaging service is to send credentials and presentation requests to the Dock Wallet, but other clients can use it too.

Encrypt Message

POST /messaging/encrypt REQUEST

In most cases you'll want to ensure the privacy of the message by encrypting it before sending.

Code samples

# You can also use wget
curl -X POST https://api-testnet.dock.io/messaging/encrypt \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Body parameter

{
  "type": "https://didcomm.org/issue-credential/2.0/issue-credential",
  "payload": {
    "domain": "api.dock.io",
    "credentials": [{ ...vcJSON }]
  },
  "senderDid": "did:dock:xyz",
  "algorithm": "ECDH-1PU+A256KW",
  "recipientDids": [
    "did:dock:xyz"
  ]
}

Parameters

Name In Type Required Description
body body object true The recipients, sender and message
» type body string false none
» payload body object true none
» senderDid body string true none
» algorithm body string false none
» recipientDids body [oneOf] true none

Enumerated Values

Parameter Value
» algorithm ECDH-1PU+A256KW
» algorithm ECDH-ES+A256KW

Example responses

200 Response

{
  "code": 0
}

Responses

Status Meaning Description Schema
200 OK Message has been encrypted, returning an encrypted DIDComm Message Response
400 Bad Request Message failed to encrypt Error
402 Payment Required Transaction limit reached or upgrade required to proceed Error
404 Not Found DID was not found Error

Decrypt Message

POST /messaging/decrypt REQUEST

Code samples

# You can also use wget
curl -X POST https://api-testnet.dock.io/messaging/decrypt \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Body parameter

{
  "jwe": {}
}

Parameters

Name In Type Required Description
body body object true The JWM
» jwe body object true none

Example responses

200 Response

{
  "code": 0
}

Responses

Status Meaning Description Schema
200 OK Message has been decrypted, returning a DIDComm message Response
400 Bad Request Message failed to decrypt Error
402 Payment Required Transaction limit reached or upgrade required to proceed Error
404 Not Found DID was not found Error

Signing Messages

POST /messaging/sign REQUEST

Signing a message helps to prove to the recipient that the message is valid and unaltered. The message will be signed as a Base64 encoded JWT.

Code samples

# You can also use wget
curl -X POST https://api-testnet.dock.io/messaging/sign \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Body parameter

{
  "payload": {},
  "senderDid": "string",
  "type": "string"
}

Parameters

Name In Type Required Description
body body object true The message payload
» payload body object true none
» senderDid body string true none
» type body string false none

Example responses

200 Response

"eyJhRU...p6byJ9.eyJpZ...em8iXV19.RIHJunaOq0SnQqYjG...BXo4ozHjWAMfqR0czB0rR4emWF0MeWOCXXSJra4ttCFAQ"

Responses

Status Meaning Description Schema
200 OK Message has been signed Response
400 Bad Request Message failed to sign Error
402 Payment Required Transaction limit reached or upgrade required to proceed Error
404 Not Found DID was not found Error

Verifying a Message

POST /messaging/verify REQUEST

Verify that the message is valid.

Code samples

# You can also use wget
curl -X POST https://api-testnet.dock.io/messaging/verify \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Body parameter

{
  "jws": "string"
}

Parameters

Name In Type Required Description
body body object true The message payload
» jws body string true none

Example responses

200 Response

{
    "verified": true,
    "payload": {
        "id": "14a31880-e864-11ed-ab4c-3f9fbca4f00d",
        "type": "https://example.com/protocols/lets_do_lunch/1.0/proposal",
        "created_time": 1682975205,
        "from": "did:example:alice",
        "body": {
            "some": "test-value"
        },
        "reply_to": [
            [
                "did:example:alice"
            ]
        ]
    }
}

Responses

Status Meaning Description Schema
200 OK Message is verified Response
400 Bad Request Message failed to verify Error
402 Payment Required Transaction limit reached or upgrade required to proceed Error
404 Not Found DID was not found Error

Send Message

POST /messaging/send REQUEST

Sends a DIDComm message using our relay service and DID service endpoints, it also returns a URL for QR code scanning. Supports encrypted, plaintext and signed DIDComm messages. You can generate an encrypted DIDComm message by calling the /messaging/encrypt route.

The typ attribute must be a DIDComm type (i.e. starts with "application/didcomm").

Code samples

# You can also use wget
curl -X POST https://api-testnet.dock.io/messaging/send \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'

Body parameter

{
  "to": "string",
  "message": {
    "typ": "string"
  }
}

Parameters

Name In Type Required Description
body body object true The message payload
» to body string true none
» message body Message true none

Example responses

200 Response

{
    "sent": true,
    "qrUrl": "didcomm://https://relay.dock.io/read/64502e3243455b67f93f95557"
}

Responses

Status Meaning Description Schema
200 OK Message has been sent Response
400 Bad Request Message failed to send Error
402 Payment Required Transaction limit reached or upgrade required to proceed Error
404 Not Found DID was not found Error

Schemas

Object Schemas

Data Schemas are useful when enforcing a specific structure on a collection of data like a Verifiable Credential. Other than that, Data Verification schema and Data Encoding Schemas are used to verify and map the structure and contents of a Verifiable Credential.

These are the schemas used in all API operations mentioned before, such as Error, Credential, Jobs, Anchor, Registry, and so on.

For a detailed example of the schema workflow. Please refer here.

Error

{
  "status": 0,
  "type": "string",
  "message": "string"
}

This is a schema for an API Error.

Properties

Name Type Required Description
status integer false Status of the error.
type string false Type of the error.
message string false Message of the error.

Hex32

"string"

32 byte hex string. Ignoring higher base (base64) for simplicity.

Properties

Name Type Required Description
Hex32 string false 32 byte hex string. Ignoring higher base (base64) for simplicity.

JobStartedResult

{
  "id": "string",
  "data": {
    "did": "did:dock:xyz",
    "hexDid": "0x00",
  }
}

Object containing unique id of the background task and associated data. This id can be used to query the job status.

Properties

Name Type Description
id JobId Unique id of the background task. This id can be used to query the job status.
data object Data of the object.

JobId

"string"

Unique id of the background task. This id can be used to query the job status

JobStatus

"in_progress"

This is a schema used in Job operation to get a status of the job.

Enumerated Values

Property Value Description
JobStatus todo or finalized or in_progress or error. Job Status variants.

JobDesc

{
  "id": "string",
  "result": {},
  "status": "todo",

}

This is a schema used in Job operation to get description of the job including the result if it is available.

Properties

Name Type Description
id JobId Unique id of the background task. This id can be used to query the job status.
status JobStatus Status of the job.
result object false

DIDDock

"did:dock:xyz"

DID as fully qualified, e.g., did:dock:.

Properties

Name Type Required Description
DID string false DID as fully qualified, e.g., did:dock:. You cannot specify your own DID, the DID value will be randomly generated.

KeyType

"sr25519"

This is a schema type of public key for DID.

Enumerated Values

Property Value Description
KeyType sr25519 or ed25519 or secp256k1 keyType DID variants.

SigType

"Sr25519Signature2020"

This is a schema used in Presentation operation that represents a type of signature.

Enumerated Values

Property Value Description
SigType Sr25519Signature2020 or Ed25519Signature2018 or EcdsaSecp256k1Signature2019 SigType signature variants.

ProofPurpose

"assertionMethod"

This is a schema that represents a purpose of credential.

Enumerated Values

Property Value Description
ProofPurpose assertionMethod or authentication Purpose of credential.

Context

[
  "string"
]

This is a schema that represents a JSON-LD context used in DID and Presentation.

DIDDoc

{
  "@context": [
    "string"
  ],
  "id": "did:dock:xyz",
  "authentication": [
    {}
  ]
}

This is a schema that represents a DID document. The current set of properties is incomplete

Properties

Name Type Required Description
@context Context false JSON-LD context.
id DIDDock false DID as fully qualified, e.g., did:dock:.
authentication array false DID authentication.

Credential

{
  "context": [
    "string"
  ],
  "type": [
    "string"
  ],
  "subject": {},
  "issuer": "did:dock:xyz",
  "issuanceDate": "2019-08-24T14:15:22Z",
  "expirationDate": "2019-08-24T14:15:22Z",
  "status": "90b7dc6e8642bf1425c5a5ef2c3ff62bb689770843fdc0e2d79b97beb6c73311"
}

This is a schema that represents a credential format expected by API caller when issuing a credential.

Properties

Name Type Required Description
id string(uri) false Credential ID. The default value is a creds.dock.io uri with random ID.
context [string or object] false Credential context array of string URIs and/or embedded JSON-LD context objects. If no context parameter is supplied, we will auto generate contexts for you. If you do supply this parameter, you must ensure that all JSON-LD terms are defined. This is for advanced users.
type [string] false Credential type. The default value is ['VerifiableCredential']
subject object or [object] true Credential subject or subjects array.
schema string false Schema ID returned by create schema route or a valid URI
issuer DIDDock false Credential issuer. DID as fully qualified, e.g., did:dock:. If not supplied the credential will not be signed.
issuanceDate string(date-time[RFC3339]) false The date and time in GMT that the credential was issued specified in RFC 3339 format. The issuanceDate will be automatically set if not provided.
expirationDate string(date-time[RFC3339]) false The date and time in GMT that the credential expired is specified in RFC 3339 format. The default value of the expirationDate will be empty if the user does not provide it.
status object or string false Revocation registry id or user supplied status object containg a Dock revocation registry identifier.

VerifiablePresentation

{
  "@context": [
    "string"
  ],
  "id": "http://example.com",
  "type": [
    "string"
  ],
  "verifiableCredential": {
    "@context": [
      "string"
    ],
    "id": "https://creds.dock.io/f087cbfabc90f8b996971ba47598e82b1a03523cb9460217ad58a819cd9c09eb",
    "type": [
      "string"
    ],
    "credentialSubject": {},
    "issuer": "did:dock:xyz",
    "issuanceDate": "2019-08-24T14:15:22Z",
    "expirationDate": "2019-08-24T14:15:22Z",
    "credentialStatus": {},
    "proof": {
      "type": "Sr25519Signature2020",
      "proofPurpose": "assertionMethod",
      "verificationMethod": "string",
      "created": "2019-08-24T14:15:22Z",
      "proofValue": "string"
    }
  },
  "proof": {
    "type": "Sr25519Signature2020",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "string",
    "created": "2019-08-24T14:15:22Z",
    "proofValue": "string"
  }
}

This is a schema that represents a Verifiable (signed) Presentation returned by API. The current set of properties is almost complete

Properties

Name Type Required Description
@context Context true JSON-LD context.
id string(uri) true Verifiable (signed) presentation id.
type string true Verifiable (signed) presentation type.
verifiableCredential VerifiableCredential true Verifiable (signed) Credential returned by API. The current set of properties is almost complete.
proof object true Proof of credential.

Child Properties of Proof

Name Type Required Description
type SigType true Type of signature.
proofPurpose ProofPurpose true Purpose of credential.
verificationMethod string true Verification method.
created string(date-time[RFC3339]) true The date and time in GMT that the credential was created specified in RFC 3339 format.
proofValue string true none

VerifiableCredential

{
  "@context": [
    "string"
  ],
  "id": "https://creds.dock.io/f087cbfabc90f8b996971ba47598e82b1a03523cb9460217ad58a819cd9c09eb",
  "type": [
    "string"
  ],
  "credentialSubject": {},
  "issuer": "did:dock:xyz",
  "issuanceDate": "2019-08-24T14:15:22Z",
  "expirationDate": "2019-08-24T14:15:22Z",
  "credentialStatus": {},
  "proof": {
    "type": "Sr25519Signature2020",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "string",
    "created": "2019-08-24T14:15:22Z",
    "proofValue": "string"
  }
}

This is a schema that represents a verifiable (signed) Credential returned by API. The current set of properties is almost complete.

Properties

Name Type Required Description
@context Context false JSON-LD context.
id string(uri) false Credential id.
type [string] false Credential type.
credentialSubject any false Credential subject.
issuer DIDDock false Credential issuer or DID as fully qualified, e.g., did:dock:.
issuanceDate string(date-time[RFC3339]) false The date and time in GMT that the credential was issued specified in RFC 3339 format. The issuanceDate will be automatically set if not provided.
expirationDate string(date-time[RFC3339]) false The date and time in GMT that the credential expired is specified in RFC 3339 format. The default value of the expirationDate will be empty if the user does not provide it.
credentialStatus any false Revocation registry id or user supplied status object.
proof object false Proof of credential.

Child Properties of Proof

Name Type Required Description
type SigType false Type of signature.
proofPurpose ProofPurpose false Purpose of credential.
verificationMethod string false Verification method.
created string(date-time[RFC3339]) false The date and time in GMT that the credential was created specified in RFC 3339 format.
proofValue string false Value of credential.

Anchor

{
  "type": "single/batch",
  "proofs": [],
  "blockHash": "string",
  "root": "string",
  "created_at": "YYYY-"
}

An anchor, either a batched or single is the information that constitutes the credentials' proof of existence. The schema includes anchor, type (single, batch), block hash, block number and accompanying data (root, proofs) if any. It depends if the anchor was created using API or not.

Registry

{
  "addOnly": true,
  "policy": [
    "did:dock:xyz"
  ]
}

This is a schema that represents a Revocation registry used in Revocation or Unrevocation.

Properties

Name Type Required Description
addOnly boolean false If the addOnly value is true, they cannot unrevoke and delete the registry. The default value for this is false.
policy [DIDDock] false Only one policy supported as of now called OneOf.

VerificationResponse

{
  "verified": true,
  "results": [...]
}

This is a schema that is used to define whether a credential/presentation is verified or not

Response

{
  "code": 0
}

This is a schema that represents a default response for a request made.

Message

{
  "to": ["did:example:bob"],
  "ciphertext": "eyJhsad...AQ",
  "typ":"application/didcomm..."
}

This is a schema that represents a message send request. If the message is signed or encrypted use the ciphertext field. The typ field must be a valid DIDComm message type.