Website Dock Certs

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.

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

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.

Endpoints

POST /credentials GET /credentials/{id} DELETE /credentials/{id}

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.

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

This operation counts towards your monthly transaction/credential issuance limit for each successful call

Parameters

NameInTypeRequiredDescription

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

ParameterValueDescription

algorithm

ed25519 or secp256k1 or sr25519 or dockbbs+

The algorithm used to sign the credential.

Responses

StatusMeaningDescriptionSchema

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

POST /credentials REQUEST PAYLOAD

{
  "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"
  }
}
POST /credentials REQUEST CURL
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"
  }
}'
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"
}

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.

This operation counts towards your monthly transaction/credential issuance limit for each successful call.

Parameters

NameInTypeRequiredDescription

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.

Responses

StatusMeaningDescriptionSchema

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

POST /credentials/request-claims REQUEST PAYLOAD

{
  "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
  }
}
POST /credentials/request-claims REQUEST CURL
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
  }
}'
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
  }
}

Get Credential

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

NameInTypeRequiredDescription

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

Responses

StatusMeaningDescriptionSchema

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

GET /credentials/{id} REQUEST CURL
curl --location --request GET 'https://api.dock.io/credentials/credential_id?password=test' \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''
200 Response
{
  "id": "https://creds.dock.io/f087cbfabc90f8b996971ba47598e82b1a03523cb9460217ad58a819cd9c09eb",
  "byteSize": 1074,
  "issuerKey": "did:dock:5CU97DhQ3mnbxPAiYw3GoRqFcnvCLGuHj3MS8evD8sARmg3e#KWAtkADdAy1rCiysr4cPZre4Lj7GFWGqyN5mP5X8xuzAnGzAb                     ",
  "createdAt": "2021-12-21T01:36:23.062Z",
  "credential": { ... }
}

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.

Parameters

NameInTypeRequiredDescription

did

path

string

true

The ID of the credential (as a full URL-encoded URI).

Responses

StatusMeaningDescriptionSchema

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

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

Get Credentials Metadata

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

NameInTypeRequiredDescription

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

StatusMeaningDescriptionSchema

200

OK

The request was successful and will return the credential metadata and its JSON contents.

GET /credentials REQUEST
curl --location --request GET 'https://api.dock.io/credentials' \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''
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
  }
]
PreviousProfilesNextPresentations

Last updated