docs/_static/vdr/v2.yaml
openapi: "3.0.0"
info:
title: Nuts Verifiable Data Registry API spec
description: API specification for the Verifiable Data Registry
version: 2.0.0
license:
name: GPLv3
servers:
- url: http://localhost:8081
paths:
/internal/vdr/v2/did/{did}:
parameters:
- name: did
in: path
description: URL encoded DID.
required: true
content:
plain/text:
schema:
type: string
example: "did:web:example.com:iam:123"
get:
summary: "Resolves a DID document"
description: |
Resolves a DID document.
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: "resolveDID"
tags:
- DID
responses:
"200":
description: DID document has been found and returned.
content:
application/json:
schema:
$ref: '#/components/schemas/DIDResolutionResult'
default:
$ref: '../common/error_response.yaml'
/internal/vdr/v2/subject:
post:
summary: Creates new DID Documents for a subject.
description: |
New DIDs and DID Documents are created. It will only create new DID Documents for enabled DID methods.
Each method generates keys and identifiers according to their own specification.
error returns:
* 400 - Returned in case of malformed DID in the request body
* 500 - An error occurred while processing the request
operationId: "createSubject"
tags:
- Subject
requestBody:
description: Options for the subject creation. keys.assertionKey settings are ignored.
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSubjectOptions'
responses:
"200":
description: "New subject has been created successfully. Returns the DID documents and subject."
content:
application/json:
schema:
$ref: '#/components/schemas/SubjectCreationResult'
default:
$ref: '../common/error_response.yaml'
get:
summary: Lists all subjects and their DIDs.
description: |
Lists all subjects.
error returns:
* 500 - An error occurred while processing the request
operationId: "listSubjects"
tags:
- Subject
responses:
"200":
description: "List of all subjects and their DIDs."
content:
application/json:
schema:
type: object
additionalProperties:
type: array
items:
type: string
default:
$ref: '../common/error_response.yaml'
/internal/vdr/v2/subject/{id}:
parameters:
- name: id
in: path
description: URL encoded subject.
required: true
content:
plain/text:
schema:
type: string
example: "90BC1AE9-752B-432F-ADC3-DD9F9C61843C"
get:
summary: Lists all DIDs for a subject
description: |
Lists all DIDs for a subject.
error returns:
* 500 - An error occurred while processing the request
operationId: "subjectDIDs"
tags:
- Subject
responses:
"200":
description: "List of all DIDs for a subject."
content:
application/json:
schema:
type: array
items:
type: string
default:
$ref: '../common/error_response.yaml'
delete:
summary: Deactivate all DID Documents for a subject.
description: |
error returns:
* 400 - the subject param was malformed
* 404 - Corresponding subject could not be found
* 409 - The subject is already deactivated
* 500 - An error occurred while processing the request
operationId: "deactivate"
tags:
- Subject
responses:
"204":
description: DID documents have been deactivated.
default:
$ref: '../common/error_response.yaml'
/internal/vdr/v2/subject/{id}/service:
parameters:
- name: id
in: path
description: URL encoded subject.
required: true
content:
plain/text:
schema:
type: string
example: "90BC1AE9-752B-432F-ADC3-DD9F9C61843C"
post:
summary: Adds a service to DID documents of a subject.
description: |
It adds the given service to the DID Documents of a subject after generating a Service ID.
Duplicate services registrations (same type and serviceEndpoint) are ignored.
error returns:
* 400 - Returned in case of malformed DID or service
* 404 - Subject could not be found
* 500 - An error occurred while processing the request
operationId: createService
tags:
- Subject
requestBody:
description: Service to be added to the DID document.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceRequest'
responses:
"200":
description: "New service has been added successfully. Returns a service per DID Document."
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Service'
default:
$ref: '../common/error_response.yaml'
get:
summary: "Find services of a subject"
parameters:
- name: type
in: query
description: |
Type of the service to filter for. If specified, only services with the given service type are returned.
required: false
schema:
type: string
example: "api"
- name: endpointType
in: query
description: |
The data type of the service endpoint to filter for. If specified, only services with the given endpoint type are returned.
Endpoint types as mapped as follows:
- string: serviceEndpoint contains a JSON string
- array: serviceEndpoint contains a JSON array
- object: serviceEndpoint contains a JSON object (key-value map)
If not specified, services are not filtered on their endpoint data type.
required: false
schema:
type: string
enum:
- string
- object
- array
description: |
Find services for a subject. All DID documents of the subject have the same services.
It returns the services that match specified filter parameters.
error returns:
* 400 - Returned in case of malformed DID.
* 404 - Subject could not be found
* 500 - An error occurred while processing the request
operationId: "findServices"
tags:
- Subject
responses:
"200":
description: filtered services are returned.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Service'
examples:
string:
summary: This example shows a response with a service containing a string endpoint.
value: |
[
{
"id": "did:web:example.com:1",
"type": "api",
"serviceEndpoint": "https://example.com/api"
}
]
object:
summary: This example shows a response with a service containing an object endpoint.
value: |
[
{
"id": "did:web:example.com:1",
"type": "api",
"serviceEndpoint": {
"server1": "https://example.com/api",
"server2": "https://alt.example.com/api"
}
}
]
array:
summary: This example shows a response with a service containing an array endpoint.
value: |
[
{
"id": "did:web:example.com:1",
"type": "api",
"serviceEndpoint": ["https://example.com/api", "https://alt.example.com/api"]
}
]
default:
$ref: '../common/error_response.yaml'
/internal/vdr/v2/subject/{id}/service/{serviceId}:
parameters:
- name: id
in: path
description: URL encoded Subject.
required: true
content:
plain/text:
schema:
type: string
example: "90BC1AE9-752B-432F-ADC3-DD9F9C61843C"
- name: serviceId
in: path
description: URL encoded ID identifying the service.
required: true
content:
plain/text:
schema:
type: string
examples:
long-form:
value: "did:web:example.com:iam:013c6fda-73e8-45ee-9220-48652dba854b#3106f751-59e3-440f-b57b-39a96a2da6c6"
summary: Long form of a service.ID starting with a DID
short-form:
value: "#3106f751-59e3-440f-b57b-39a96a2da6c6"
summary: "Short form of a service.ID containing only the fragment. Must include the # prefix."
delete:
summary: Delete a specific service from the subject
description: |
Removes the service from all DID Documents in the subject. Matching is done on the fragment of the id.
No cascading will happen for references to the service.
Make sure to only URL encode the pound (#) as %23 in the serviceId. Do not encode the colons (:).
error returns:
* 400 - Returned in case of malformed subject or service ID
* 404 - Corresponding subject or service could not be found
* 500 - An error occurred while processing the request
tags:
- Subject
operationId: deleteService
responses:
"204":
description: The service was successfully deleted
default:
$ref: '../common/error_response.yaml'
post:
summary: Updates a service for the subject
description: |
It replaces the given service in all DID Documents of the subject by deleting the current service and adding the provided service with a newly generated ID.
Make sure to only URL encode the pound (#) as %23 in the serviceId. Do not encode the colons (:).
error returns:
* 400 - Returned in case of malformed subject or service ID
* 404 - Corresponding subject or service could not be found
* 409 - Duplicate service type
* 500 - An error occurred while processing the request
tags:
- Subject
operationId: updateService
requestBody:
description: New version of the service.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceRequest'
responses:
"200":
description: "Service has been updated successfully. Returns the service."
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Service'
default:
$ref: '../common/error_response.yaml'
/internal/vdr/v2/subject/{id}/verificationmethod:
parameters:
- name: id
in: path
description: URL encoded subject.
required: true
content:
plain/text:
schema:
type: string
example: "90BC1AE9-752B-432F-ADC3-DD9F9C61843C"
post:
summary: Creates and adds one or more verificationMethods to each DID document in the subject.
description: |
Based on the keyCreationOptions, it will add an RSA key for encryption usage and an EC key for signing and authentication.
error returns:
* 404 - Corresponding subject could not be found
* 500 - An error occurred while processing the request
operationId: addVerificationMethod
tags:
- Subject
requestBody:
description: options for key creation.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/KeyCreationOptions'
responses:
"200":
description: "New verification method has been created and added successfully. Returns the verification method."
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/VerificationMethod'
default:
$ref: '../common/error_response.yaml'
/iam/{id}/did.json:
parameters:
- name: id
in: path
description: ID of DID.
required: true
example: EwVMYK2ugaMvRHUbGFBhuyF423JuNQbtpes35eHhkQic
schema:
type: string
get:
summary: Returns the did:web DID for the specified tenant.
description: |
Returns the did:web DID for the specified tenant, if it is owned by this node.
operationId: "getTenantWebDID"
tags:
- DID
responses:
"200":
description: DID has been found and returned.
content:
application/json:
schema:
$ref: '#/components/schemas/DIDDocument'
"404":
description: DID does not exist.
/.well-known/did.json:
get:
summary: Returns the root did:web DID of this domain.
description: |
Returns the root did:web DID of this domain, if it is owned by this node.
operationId: "getRootWebDID"
tags:
- DID
responses:
"200":
description: DID has been found and returned.
content:
application/json:
schema:
$ref: '#/components/schemas/DIDDocument'
"404":
description: DID does not exist.
# /internal/vdr/v2/did/{did}/verificationmethod/{id}:
# parameters:
# - name: did
# in: path
# description: URL encoded DID.
# required: true
# content:
# plain/text:
# schema:
# type: string
# example: "did:web:example.com:iam:123"
# - name: id
# in: path
# description: URL encoded ID identifying the verification method.
# required: true
# example: "did:web:example.com:iam:013c6fda-73e8-45ee-9220-48652dba854b#3106f751-59e3-440f-b57b-39a96a2da6c6"
# schema:
# type: string
# delete:
# summary: Delete a specific verification method
# description: |
# Removes the verification method from the DID Document.
#
# error returns:
# * 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:
KeyCreationOptions:
type: object
description: Options for the key creation.
required:
- assertionKey
- encryptionKey
properties:
assertionKey:
type: boolean
description: If true, an EC keypair is generated and added to the DID Documents as a assertion, authentication, capability invocation and capability delegation method.
encryptionKey:
type: boolean
description: If true, an RSA keypair is generated and added to the DID Documents as a key agreement method.
CreateSubjectOptions:
type: object
description: Options for the subject creation.
properties:
subject:
type: string
description: controls the DID subject to which all created DIDs are bound. If not given, a uuid is generated and returned.
keys:
$ref: '#/components/schemas/KeyCreationOptions'
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'
Service:
$ref: '../common/ssi_types.yaml#/components/schemas/Service'
ServiceRequest: # copy of Service minus ID field
type: object
description: A service supported by a DID subject.
required:
- type
- serviceEndpoint
properties:
type:
description: The type of the endpoint.
type: string
serviceEndpoint:
description: Either a URI or a complex object.
DIDResolutionResult:
required:
- document
- documentMetadata
properties:
document:
$ref: '#/components/schemas/DIDDocument'
documentMetadata:
$ref: '#/components/schemas/DIDDocumentMetadata'
SubjectCreationResult:
type: object
description: Result of a subject creation request. Contains the subject and any created DID Documents.
required:
- subject
- documents
properties:
subject:
type: string
description: The subject of the created DID Documents.
documents:
type: array
items:
$ref: '#/components/schemas/DIDDocument'
securitySchemes:
jwtBearerAuth:
type: http
scheme: bearer
security:
- {}
- jwtBearerAuth: []