docs/_static/vdr/v1.yaml
openapi: "3.0.0"
info:
title: Nuts Verifiable Data Registry API spec
description: API specification for the Verifiable Data Registry
version: 1.0.0
license:
name: GPLv3
servers:
- url: http://localhost:8081
paths:
/internal/vdr/v1/did:
post:
summary: Creates a new Nuts DID
description: |
The DID Document will be created according to the given request. If a combination of options is not allowed, a 400 is returned.
The default values for selfControl, assertionMethod, keyAgreement, and capabilityInvocation are true. The default for controllers is an empty list. All other options default to false.
Only a single keypair will be generated. All enabled methods will reuse the same key pair. A seperate keypair will be generated to generate the DID if SelfControl is false.
error returns:
* 400 - Invalid (combination of) options
* 500 - An error occurred while processing the request
operationId: "createDID"
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DIDCreateRequest'
tags:
- DID
responses:
"200":
description: "New DID has been created successfully. Returns the DID document."
content:
application/json:
schema:
$ref: '#/components/schemas/DIDDocument'
default:
$ref: '../common/error_response.yaml'
/internal/vdr/v1/did/{did}:
parameters:
- name: did
in: path
description: URL encoded DID.
required: true
example: did:nuts:EwVMYK2ugaMvRHUbGFBhuyF423JuNQbtpes35eHhkQic
schema:
type: string
get:
parameters:
- name: versionId
in: query
description: |
If a versionId parameter is provided, the DID resolution algorithm returns a specific version of the DID document.
The version is the Sha256 hash of the document.
The DID parameters versionId and versionTime are mutually exclusive.
See [the did resolution spec about versioning](https://w3c-ccg.github.io/did-resolution/#versioning)
required: false
example: "4960afbdf21280ef248081e6e52317735bbb929a204351291b773c252afeebf4"
schema:
type: string
- name: versionTime
in: query
description: |
If a versionTime parameter is provided, the DID resolution algorithm returns a specific version of the DID document.
The DID parameters versionId and versionTime are mutually exclusive.
See [the did resolution spec about versioning](https://w3c-ccg.github.io/did-resolution/#versioning)
required: false
example: "2021-11-03T08:25:13Z"
schema:
type: string
summary: "Resolves a Nuts DID document"
description: |
Resolves a Nuts DID document. It also resolves deactivated documents.
error returns:
* 400 - Returned in case of malformed DID
* 404 - Corresponding DID document could not be found
* 500 - An error occurred while processing the request
operationId: "getDID"
tags:
- DID
responses:
"200":
description: DID has been found and returned.
content:
application/json:
schema:
$ref: '#/components/schemas/DIDResolutionResult'
default:
$ref: '../common/error_response.yaml'
put:
summary: Updates a Nuts DID document.
description: |
Updates a Nuts DID document.
error returns:
* 400 - DID document could not be updated because the DID param was malformed or the DID document is invalid
* 403 - DID document could not be updated because the DID is not managed by this node
* 404 - Corresponding DID document could not be found
* 409 - DID document could not be updated because the document is deactivated or its controllers are deactivated
* 500 - An error occurred while processing the request
operationId: "updateDID"
tags:
- DID
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DIDUpdateRequest'
responses:
"200":
description: DID document has been updated.
content:
application/json:
schema:
$ref: '#/components/schemas/DIDDocument'
default:
$ref: '../common/error_response.yaml'
delete:
summary: Deactivates a Nuts DID document according to the specification.
description: |
Updates a Nuts DID document.
error returns:
* 400 - DID document could not be deleted because the DID param was malformed
* 403 - DID document could not be deleted because the DID is not managed by this node
* 404 - Corresponding DID document could not be found
* 409 - DID document could not be deactivated because the the document was already deactivated
* 500 - An error occurred while processing the request
operationId: "deactivateDID"
tags:
- DID
responses:
"200":
description: DID document has been deactivated.
default:
$ref: '../common/error_response.yaml'
/internal/vdr/v1/did/conflicted:
get:
summary: "Retrieve the list of conflicted DID documents"
description: |
Resolves DID documents with a conflict. It returns both the DID Document and metadata of the DID Document.
error returns:
* 500 - An error occurred while processing the request
operationId: "conflictedDIDs"
tags:
- DID
responses:
"200":
description: List of conflicting DID Documents. Empty list if there are none.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DIDResolutionResult'
default:
$ref: '../common/error_response.yaml'
/internal/vdr/v1/did/{did}/verificationmethod:
parameters:
- name: did
in: path
description: URL encoded DID.
required: true
example: did:nuts:EwVMYK2ugaMvRHUbGFBhuyF423JuNQbtpes35eHhkQic
schema:
type: string
post:
summary: Creates and adds a new verificationMethod to the DID document.
description: |
It creates a new private public keypair. The public key is wrapped in verificationMethod. This method is added to the DID Document.
By default, the key usage (verificationMethod relationships) is the same as when creating a new DID document.
To alter this, provide a body specifying the key usage.
error returns:
* 403 - Verification method could not be added because the DID is not managed by this node
* 404 - Corresponding DID document could not be found
* 500 - An error occurred while processing the request
operationId: addNewVerificationMethod
tags:
- DID
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VerificationMethodRelationship'
responses:
"200":
description: "New verification method has been created and added successfully. Returns the DID document."
content:
application/json:
schema:
$ref: '#/components/schemas/VerificationMethod'
default:
$ref: '../common/error_response.yaml'
/internal/vdr/v1/did/{did}/verificationmethod/{kid}:
parameters:
- name: did
in: path
description: URL encoded DID.
required: true
example: did:nuts:EwVMYK2ugaMvRHUbGFBhuyF423JuNQbtpes35eHhkQic
schema:
type: string
- name: kid
in: path
description: URL encoded DID identifying the verification method.
required: true
example: "did:nuts:EwVMYK2ugaMvRHUbGFBhuyF423JuNQbtpes35eHhkQic#zx1alkbvj2mqxi55WSVYWv_rek0uNO2iTZaqTTULpCE"
schema:
type: string
delete:
summary: Delete a specific verification method
description: |
Removes the verification method from the DID Document.
Revokes the public key with the corresponding key-id.
Note: Other verification methods with different key-ids with the same private key will still be valid.
error returns:
* 403 - Verification method could not be deleted because the DID is not managed by this node
* 404 - Corresponding DID document or verification method could not be found
* 500 - An error occurred while processing the request
tags:
- DID
operationId: deleteVerificationMethod
responses:
"204":
description: Verification Method was successfully deleted
default:
$ref: '../common/error_response.yaml'
components:
schemas:
DIDDocument:
$ref: '../common/ssi_types.yaml#/components/schemas/DIDDocument'
DIDDocumentMetadata:
$ref: '../common/ssi_types.yaml#/components/schemas/DIDDocumentMetadata'
VerificationMethod:
$ref: '../common/ssi_types.yaml#/components/schemas/VerificationMethod'
DIDResolutionResult:
required:
- document
- documentMetadata
properties:
document:
$ref: '#/components/schemas/DIDDocument'
documentMetadata:
$ref: '#/components/schemas/DIDDocumentMetadata'
DIDUpdateRequest:
required:
- document
- currentHash
properties:
document:
$ref: '#/components/schemas/DIDDocument'
currentHash:
type: string
description: The hash of the document in hex format. No longer used, contents ignored.
deprecated: true
DIDCreateRequest:
properties:
assertionMethod:
type: boolean
description: indicates if the generated key pair can be used for assertions.
default: true
authentication:
type: boolean
description: indicates if the generated key pair can be used for authentication.
default: false
capabilityInvocation:
type: boolean
description: |
indicates if the generated key pair can be used for altering DID Documents.
In combination with selfControl = true, the key can be used to alter the new DID Document.
Defaults to true when not given.
default: true
capabilityDelegation:
type: boolean
description: indicates if the generated key pair can be used for capability delegations.
default: true
keyAgreement:
type: boolean
description: indicates if the generated key pair can be used for Key agreements.
default: true
VerificationMethodRelationship:
properties:
assertionMethod:
type: boolean
description: indicates if the generated key pair can be used for assertions.
default: true
authentication:
type: boolean
description: indicates if the generated key pair can be used for authentication.
default: false
capabilityInvocation:
type: boolean
description: |
indicates if the generated key pair can be used for altering DID Documents.
In combination with selfControl = true, the key can be used to alter the new DID Document.
Defaults to true when not given.
default: true
capabilityDelegation:
type: boolean
description: indicates if the generated key pair can be used for capability delegations.
default: true
keyAgreement:
type: boolean
description: indicates if the generated key pair can be used for Key agreements.
default: true
selfControl:
type: boolean
description: whether the generated DID Document can be altered with its own capabilityInvocation key.
default: true
securitySchemes:
jwtBearerAuth:
type: http
scheme: bearer
security:
- {}
- jwtBearerAuth: []