Registries

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.

If you want to revoke BBS+ credentials, you must create a registry with type `DockVBAccumulator2022`. For revoking other credentials, you can use `StatusList2021Entry` or `CredentialStatusList2017`.

Endpoints

POST /registries GET /registries GET /registries/{id} POST /registries/{id} DELETE /registries/{id}\

Create Registry

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

NameInTypeRequiredDescription

addOnly

body

boolean

false

True/false options. The default value is "false".

policy

body

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

ParameterValueDescription

type

StatusList2021Entry or CredentialStatusList2017 or DockVBAccumulator2022

The type used in registry creation.

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"
}

Responses

StatusMeaningDescriptionSchema

200

The request was successful and will try to create the registry.

400

The request was unsuccessful, because of invalid params, e.g., policy not supported.

402

Transaction limit reached or upgrade required to proceed

200 Response

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

List Registries

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

For now, only one policy is supported, and each registry is owned by a single DID.

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)

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'{

  }'

Responses

StatusMeaningDescriptionSchema

200

The request was successful and will return all registries created by the user.

Inline

402

Transaction limit reached or upgrade required to proceed

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"
  }
]

Get Registry

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

NameInTypeRequiredDescription

id

path

true

Revocation registry id.

GET /registries/{id} REQUEST

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

Responses

StatusMeaningDescriptionSchema

200

The request was successful and will return the revocation registry metadata.

404

The request was unsuccessful, because the registry was not found.

402

Transaction limit reached or upgrade required to proceed

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"
}

Revoke/Unrevoke Credential

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

NameInTypeRequiredDescription

id

path

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

ParameterValueDescription

action

revoke or unrevoke

Action to take on the registry.

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"
  ]
}

Responses

StatusMeaningDescriptionSchema

200

The request was successful and will try to revoke/unrevoke the credential.

400

The request was unsuccessful, because of invalid params.

404

The request was unsuccessful, because the registry was not found.

402

Transaction limit reached or upgrade required to proceed

200 Response

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

Delete Registry

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

NameInTypeRequiredDescription

id

path

true

Revocation registry id.

DELETE /registries/{id} REQUEST

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

Responses

StatusMeaningDescriptionSchema

200

The request was successful and revocation registry will be deleted.

404

The request was unsuccessful, because the registry was not found.

402

Transaction limit reached or upgrade required to proceed

200 Response

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

Last updated