Credentials

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.

Issue Credential

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.

The https://www.w3.org/2018/credentials/v1 context URI is always required and will be supplied by default at all times as mandated by the spec. If you pass a custom context, you must ensure that you define all the required JSON-LD terms. Please also note that the request format here is not the same as an issued verifiable credential. You can issue to multiple subjects per credential by passing an array of objects.

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)

The issuer property must be a DID that you control with Dock Certs.

For Polygon ID credentials:

• In order to issue Polygon ID credentials, the issuer must be a did:polygonid issuer.

• Polygon ID credentials do not support designs at this point so template field should be omitted.

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:

• Credential ID property

• Credential size in bytes

• Issuer DID

• Issuance date

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 BBS2023 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.

Issue a Credential

Creates and issues a verifiable credential with supplied data. More info about Issue a Credential

POSThttps://api-testnet.dock.io/credentials

Body

application/json

A credential issue request body for one credential

persistboolean

Whether to store an encrypted version of this credential with us. Defaults to false, if true you must supply password.

Example: true

passwordstring

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.

Example: "securepass"

templatestring (uuid)

The credential template UUID, only required for PDF and web rendering customization

Example: ""

recipientEmailstring

The holder's email for email distribution, optional. Not required for OpenID flows.

Example: ""

algorithmstring

Optional. Specifies which signing algorithm to use to sign the issued credential. Defaults to ed25519, for ZKP credendials use dockbbs.

Example: "dockbbs"

distributeboolean

Whether to distribute the credential or not based on subject DID or email address. Not required for OpenID flows.

Example: false

formatenum

Specifies the output format of the credential, either jsonld or jwt. Defaults to jsonld.

Example: "jsonld"

jsonldjwt

credential*Credential (object)

Format to create credentials with the API

Response

200400401402404

The request was successful and returns the created Verifiable Credential.

Body

application/json

@contextContext (one of)

JSON-LD context array of strings or single string

Example: "https://docknetwork.github.io/vc-schemas/basic-credential.json-ld"

array of one ofstring

idstring

typearray of string

credentialSubjectone of

objectarray of object

issuerone of

DID (string)object

issuanceDatestring (date-time)

expirationDatestring (date-time)

credentialStatusone of

Revocation registry id or user supplied status object

objectstring

proofone of

VerifiableProof (object)array of VerifiableProof (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api-testnet.dock.io/credentials', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "credential": {}
    }),
});
const data = await response.json();

Response

200400401402404

{
  "@context": "https://docknetwork.github.io/vc-schemas/basic-credential.json-ld",
  "id": "text",
  "type": [
    "text"
  ],
  "issuer": "did:dock:xyz",
  "issuanceDate": "2024-11-21T07:50:21.476Z",
  "expirationDate": "2024-11-21T07:50:21.476Z",
  "proof": {
    "type": "Ed25519Signature2018",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "text",
    "created": "2024-11-21T07:50:21.476Z",
    "proofValue": "text"
  }
}

List Credentials

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.

List Credentials

Get all credential metadata

GEThttps://api-testnet.dock.io/credentials

Query parameters

Response

200400

The request was successful and will return the credential metadata.

Body

application/json

idstring (uri)

The unique identifier for the credential, typically a URL pointing to its location or a hash value.

Example: "https://creds.dock.io/521bb7..."

issuerKeynullable string

The DID and key identifier of the issuer that signed the credential. This key is used to verify the authenticity of the credential.

Example: "did:key:z6Mk...dsmK"

issuerNamenullable string

The profile name of the issuer that signed the credential.

Example: "Dock Issuer"

typestring

The type of credential.

Example: "VerifiableCredential"

revocationRegistrystring

The registry identifier for revocation information associated with the credential.

Example: "e6d3...59d1"

revokedboolean

Indicates whether the credential has been revoked. If true, the credential is no longer valid

Example: false

createdAtstring (date-time)

The date and time when the credential metadata was created.

Example: "2024-09-20T11:13:03.445Z"

expiryDatenullable string (date-time)

The expiration date of the credential.

Example: "2024-09-20T11:13:03.445Z"

expirationDatenullable string (date-time)

Alternative field for the expiration date of the credential.

Example: "2024-09-20T11:13:03.445Z"

issuanceDatestring (date-time)

The date and time when the credential was issued.

Example: "2024-09-20T11:13:02.648Z"

byteSizeinteger

The size of the credential in bytes.

Example: 1003

persistboolean

Indicates whether the credential is persisted in storage.

Example: false

indexstring

A unique index or identifier within a collection of credentials.

Example: "1004"

subjectRefstring

A reference to the subject of the credential, typically used to identify the entity to which the credential pertains.

Example: "Dock Ref"

whitelabelnullable number

Indicates if the credential is associated with a specific whitelabel or brand.

algorithmstring

The algorithm used for creating or signing the credential.

Example: "dockbbs"

credentialVerifiableCredential (object)

Verifiable (signed) Credential returned by API. The current set of properties is almost complete

Request

JavaScriptCurlPython

const response = await fetch('https://api-testnet.dock.io/credentials', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

[
  {
    "id": "https://creds.dock.io/521bb7...",
    "issuerKey": "did:key:z6Mk...dsmK",
    "issuerName": "Dock Issuer",
    "type": "VerifiableCredential",
    "revocationRegistry": "e6d3...59d1",
    "revoked": false,
    "createdAt": "2024-09-20T11:13:03.445Z",
    "expiryDate": "2024-09-20T11:13:03.445Z",
    "expirationDate": "2024-09-20T11:13:03.445Z",
    "issuanceDate": "2024-09-20T11:13:02.648Z",
    "byteSize": 1003,
    "persist": false,
    "index": "1004",
    "subjectRef": "Dock Ref",
    "whitelabel": null,
    "algorithm": "dockbbs",
    "credential": {
      "@context": "https://docknetwork.github.io/vc-schemas/basic-credential.json-ld",
      "id": "text",
      "type": [
        "text"
      ],
      "issuer": "did:dock:xyz",
      "issuanceDate": "2024-11-21T07:50:21.476Z",
      "expirationDate": "2024-11-21T07:50:21.476Z",
      "proof": {
        "type": "Ed25519Signature2018",
        "proofPurpose": "assertionMethod",
        "verificationMethod": "text",
        "created": "2024-11-21T07:50:21.476Z",
        "proofValue": "text"
      }
    }
  }
]

Get credentials metadata and contents

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.

Get credential metadata and contents if persistent

Get credential metadata and contents if persistent

GEThttps://api-testnet.dock.io/credentials/{id}

Path parameters

id*URI (string (uri))

Valid URI

Example: "https://credentials.dock.io/1234"

Query parameters

Response

200400404

The request was successful and will return the credential metadata and its JSON contents (if password was supplied).

Body

application/json

idstring (uri)

The unique identifier for the credential, typically a URL pointing to its location or a hash value.

Example: "https://creds.dock.io/521bb7..."

issuerKeynullable string

The DID and key identifier of the issuer that signed the credential. This key is used to verify the authenticity of the credential.

Example: "did:key:z6Mk...dsmK"

issuerNamenullable string

The profile name of the issuer that signed the credential.

Example: "Dock Issuer"

typestring

The type of credential.

Example: "VerifiableCredential"

revocationRegistrystring

The registry identifier for revocation information associated with the credential.

Example: "e6d3...59d1"

revokedboolean

Indicates whether the credential has been revoked. If true, the credential is no longer valid

Example: false

createdAtstring (date-time)

The date and time when the credential metadata was created.

Example: "2024-09-20T11:13:03.445Z"

expiryDatenullable string (date-time)

The expiration date of the credential.

Example: "2024-09-20T11:13:03.445Z"

expirationDatenullable string (date-time)

Alternative field for the expiration date of the credential.

Example: "2024-09-20T11:13:03.445Z"

issuanceDatestring (date-time)

The date and time when the credential was issued.

Example: "2024-09-20T11:13:02.648Z"

byteSizeinteger

The size of the credential in bytes.

Example: 1003

persistboolean

Indicates whether the credential is persisted in storage.

Example: false

indexstring

A unique index or identifier within a collection of credentials.

Example: "1004"

subjectRefstring

A reference to the subject of the credential, typically used to identify the entity to which the credential pertains.

Example: "Dock Ref"

whitelabelnullable number

Indicates if the credential is associated with a specific whitelabel or brand.

algorithmstring

The algorithm used for creating or signing the credential.

Example: "dockbbs"

credentialVerifiableCredential (object)

Verifiable (signed) Credential returned by API. The current set of properties is almost complete

Request

JavaScriptCurlPython

const response = await fetch('https://api-testnet.dock.io/credentials/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400404

{
  "id": "https://creds.dock.io/521bb7...",
  "issuerKey": "did:key:z6Mk...dsmK",
  "issuerName": "Dock Issuer",
  "type": "VerifiableCredential",
  "revocationRegistry": "e6d3...59d1",
  "revoked": false,
  "createdAt": "2024-09-20T11:13:03.445Z",
  "expiryDate": "2024-09-20T11:13:03.445Z",
  "expirationDate": "2024-09-20T11:13:03.445Z",
  "issuanceDate": "2024-09-20T11:13:02.648Z",
  "byteSize": 1003,
  "persist": false,
  "index": "1004",
  "subjectRef": "Dock Ref",
  "whitelabel": null,
  "algorithm": "dockbbs",
  "credential": {
    "@context": "https://docknetwork.github.io/vc-schemas/basic-credential.json-ld",
    "id": "text",
    "type": [
      "text"
    ],
    "issuer": "did:dock:xyz",
    "issuanceDate": "2024-11-21T07:50:21.476Z",
    "expirationDate": "2024-11-21T07:50:21.476Z",
    "proof": {
      "type": "Ed25519Signature2018",
      "proofPurpose": "assertionMethod",
      "verificationMethod": "text",
      "created": "2024-11-21T07:50:21.476Z",
      "proofValue": "text"
    }
  }
}

Create request claims

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. After the holder submits the requested information the credential is automatically issued.

Issue a Credential after requesting claims from the user

Creates and issues a verifiable credential with supplied data + claims from the user.

POSThttps://api-testnet.dock.io/credentials/request-claims

Body

application/json

A credential issue request body for one credential

singleUseboolean

schemastring

Example: "https://docknetwork.github.io/vc-schemas/basic-credential.json"

claimsarray of string

credentialOptionsCredentialIssueRequest (object)

Response

200400402

OpenID issuer and claim request created

Body

application/json

credentialOptions*CredentialIssueRequest (object)

authProviderOpenIDAuthProviderOptions (object)

OpenID provider configuration

claimMapobject

Key/value pair mapping for OpenID claims to JSON-LD terms

singleUseboolean

issuerstring

protocolstring

Request

JavaScriptCurlPython

const response = await fetch('https://api-testnet.dock.io/credentials/request-claims', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200400402

{
  "credentialOptions": {
    "persist": true,
    "password": "securepass",
    "template": "",
    "recipientEmail": "",
    "algorithm": "dockbbs",
    "distribute": false,
    "format": "jsonld",
    "credential": {
      "id": "",
      "name": "Basic Credential",
      "description": "My first credential",
      "schema": "https://docknetwork.github.io/vc-schemas/basic-credential.json",
      "context": "https://docknetwork.github.io/vc-schemas/basic-credential.json-ld",
      "type": [
        "BasicCredential"
      ],
      "subject": {
        "id": "did:key:123",
        "name": "A. Holder"
      },
      "issuer": "did:dock:xyz",
      "issuanceDate": "2024-11-21T07:50:21.476Z",
      "expirationDate": "2030-09-20T00:13:59.270Z",
      "status": null
    }
  },
  "authProvider": {
    "url": "https://creds.dock.io/claims",
    "scope": [
      "openid"
    ],
    "clientId": "eyAic2NoZW1hIjogImh0dHBzOi8vZG9ja25ldHdvcmsuZ2l0aHViLmlvL3ZjLXNjaGVtYXMvYmFzaWMtY3JlZGVudGlhbC5qc29uIiwgImNsYWltcyI6IFsibmFtZSJdIH0=",
    "clientSecret": "gpO2IVK+OALL8W+DcFlIfFhJtNA=",
    "claimsSource": "idToken",
    "requestParameters": {
      "login_hint": "[e-mail]",
      "prompt": "login"
    }
  },
  "claimMap": {
    "name": "name"
  },
  "singleUse": false,
  "issuer": "text",
  "protocol": "default"
}

Get request claims

Lists all created request claims that are open (the holders have not submited the requested information).

List Credentials

Get all credential metadata

GEThttps://api-testnet.dock.io/credentials/request-claims

Query parameters

Response

200400

A paged array of OpenID issuers

Body

application/json

credentialOptions*CredentialIssueRequest (object)

authProviderOpenIDAuthProviderOptions (object)

OpenID provider configuration

claimMapobject

Key/value pair mapping for OpenID claims to JSON-LD terms

singleUseboolean

issuerstring

protocolstring

Request

JavaScriptCurlPython

const response = await fetch('https://api-testnet.dock.io/credentials/request-claims', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

[
  {
    "credentialOptions": {
      "persist": true,
      "password": "securepass",
      "template": "",
      "recipientEmail": "",
      "algorithm": "dockbbs",
      "distribute": false,
      "format": "jsonld",
      "credential": {
        "id": "",
        "name": "Basic Credential",
        "description": "My first credential",
        "schema": "https://docknetwork.github.io/vc-schemas/basic-credential.json",
        "context": "https://docknetwork.github.io/vc-schemas/basic-credential.json-ld",
        "type": [
          "BasicCredential"
        ],
        "subject": {
          "id": "did:key:123",
          "name": "A. Holder"
        },
        "issuer": "did:dock:xyz",
        "issuanceDate": "2024-11-21T07:50:21.476Z",
        "expirationDate": "2030-09-20T00:13:59.270Z",
        "status": null
      }
    },
    "authProvider": {
      "url": "https://creds.dock.io/claims",
      "scope": [
        "openid"
      ],
      "clientId": "eyAic2NoZW1hIjogImh0dHBzOi8vZG9ja25ldHdvcmsuZ2l0aHViLmlvL3ZjLXNjaGVtYXMvYmFzaWMtY3JlZGVudGlhbC5qc29uIiwgImNsYWltcyI6IFsibmFtZSJdIH0=",
      "clientSecret": "gpO2IVK+OALL8W+DcFlIfFhJtNA=",
      "claimsSource": "idToken",
      "requestParameters": {
        "login_hint": "[e-mail]",
        "prompt": "login"
      }
    },
    "claimMap": {
      "name": "name"
    },
    "singleUse": false,
    "issuer": "text",
    "protocol": "default"
  }
]

List Credentials

Get all credential metadata

GEThttps://api-testnet.dock.io/credentials/request-claims

Query parameters

Response

200400

A paged array of OpenID issuers

Body

application/json

credentialOptions*CredentialIssueRequest (object)

authProviderOpenIDAuthProviderOptions (object)

OpenID provider configuration

claimMapobject

Key/value pair mapping for OpenID claims to JSON-LD terms

singleUseboolean

issuerstring

protocolstring

Request

JavaScriptCurlPython

const response = await fetch('https://api-testnet.dock.io/credentials/request-claims', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

[
  {
    "credentialOptions": {
      "persist": true,
      "password": "securepass",
      "anchor": false,
      "template": "",
      "recipientEmail": "",
      "algorithm": "dockbbs",
      "distribute": false,
      "format": "jsonld",
      "credential": {
        "id": "",
        "name": "Basic Credential",
        "description": "My first credential",
        "schema": "https://docknetwork.github.io/vc-schemas/basic-credential.json",
        "context": "https://docknetwork.github.io/vc-schemas/basic-credential.json-ld",
        "type": [
          "BasicCredential"
        ],
        "subject": {
          "id": "did:key:123",
          "name": "A. Holder"
        },
        "issuer": "did:dock:xyz",
        "issuanceDate": "2024-11-21T07:50:21.682Z",
        "expirationDate": "2030-09-20T00:13:59.270Z",
        "status": null
      }
    },
    "authProvider": {
      "url": "https://creds.dock.io/claims",
      "scope": [
        "openid"
      ],
      "clientId": "eyAic2NoZW1hIjogImh0dHBzOi8vZG9ja25ldHdvcmsuZ2l0aHViLmlvL3ZjLXNjaGVtYXMvYmFzaWMtY3JlZGVudGlhbC5qc29uIiwgImNsYWltcyI6IFsibmFtZSJdIH0=",
      "clientSecret": "gpO2IVK+OALL8W+DcFlIfFhJtNA=",
      "claimsSource": "idToken",
      "requestParameters": {
        "login_hint": "[e-mail]",
        "prompt": "login"
      }
    },
    "claimMap": {
      "name": "name"
    },
    "singleUse": false,
    "issuer": "text",
    "protocol": "default"
  }
]

Delete Credential

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.

Delete a Credential

Deletes all credential metadata and contents from the client. More info about Delete Credentials

DELETEhttps://api-testnet.dock.io/credentials/{id}

Path parameters

id*URI (string (uri))

Valid URI

Example: "https://credentials.dock.io/1234"

Query parameters

Response

200400404

Credential has been deleted.

Body

application/json

object

Request

JavaScriptCurlPython

const response = await fetch('https://api-testnet.dock.io/credentials/{id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

400404

{
  "type": "text",
  "message": "text"
}