openapi: 3.0.3
info:
  title: VDX - DIF Universal Registrar
  description: VDX - DIF Compatible Universal Registrar for DIDs
  version: '0.1'
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    email: info@sphereon.com
servers:
  - url: >-
      {protocol}://{environment}.verifiable-data.com:{port}/{projectName}/universal-registrar/1.0
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      environment:
        default: api.dev
        enum:
          - api
          - api.dev
          - api.staging
      projectName:
        default: did
        description: VDX - DID Service (Compatible with DIF Universal Registrar/Resolver)
      port:
        enum:
          - '443'
          - '8443'
        default: '443'
paths:
  /create:
    post:
      operationId: createDID
      summary: Creates a DID.
      description: Creates a Decentralized Id i.e. DID returns the object.
      parameters:
        - in: query
          required: true
          name: method
          schema:
            type: string
          description: The requested DID method for the operation.
          example: key
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRequest'
      responses:
        '200':
          description: >-
            The request was successful, but the DID may not be fully created
            yet, as indicated by the "didState.state" and "jobId" output fields.
            Additional state information plus metadata are available in the
            response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateState'
        '201':
          description: >-
            The DID has been successfully created, as indicated by the
            "didState.state" output field. Additional state information
            (including the created DID) plus metadata are available in the
            response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateState'
        '400':
          description: >-
            A problem with the input fields has occurred. Additional state
            information plus metadata may be available in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateState'
        '500':
          description: >-
            An internal error has occurred. Additional state information plus
            metadata may be available in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateState'
  /update:
    post:
      operationId: updateDID
      summary: Update a DID.
      description: Updates a Decentralized Id
      parameters:
        - in: query
          required: true
          name: method
          schema:
            type: string
          description: The requested DID method for the operation.
          example: didMethod1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRequest'
      responses:
        '200':
          description: >-
            The request was successful, and the DID may or may not be fully
            updated yet, as indicated by the "didState.state" and "jobId" output
            fields. Additional state information plus metadata are available in
            the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateState'
        '400':
          description: >-
            A problem with the input fields has occurred. Additional state
            information plus metadata may be available in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateState'
        '500':
          description: >-
            An internal error has occurred. Additional state information plus
            metadata may be available in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateState'
  /deactivate:
    post:
      operationId: deactivateDID
      summary: Deactivate DID.
      description: Deactivates a DID
      parameters:
        - in: query
          required: true
          name: method
          schema:
            type: string
          description: The requested DID method for the operation.
          example: didMethod1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeactivateRequest'
      responses:
        '200':
          description: >-
            The request was successful, and the DID may or may not be fully
            deactivated yet, as indicated by the "didState.state" and "jobId"
            output fields. Additional state information plus metadata are
            available in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeactivateState'
        '400':
          description: >-
            A problem with the input fields has occurred. Additional state
            information plus metadata may be available in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeactivateState'
        '500':
          description: >-
            An internal error has occurred. Additional state information plus
            metadata may be available in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeactivateState'
  /properties:
    get:
      summary: Returns a map of properties of the resolver.
      operationId: universalRegistrarGetProperties
      responses:
        '200':
          description: Success.
          content:
            application/did+json:
              schema:
                type: object
                description: A map of properties.
  /methods:
    get:
      summary: Returns a list of supported DID methods.
      operationId: universalRegistrarGetMethods
      responses:
        '200':
          description: Success.
          content:
            application/did+json:
              schema:
                type: array
                items:
                  type: string
                description: The list of supported DID methods.
                example:
                  - key
                  - web
                  - ion
                  - factom
                  - lto
components:
  schemas:
    DeactivateRequest:
      title: Deactivate request object
      description: Data object containing information to request deactivation of DID.
      type: object
      additionalProperties: false
      required:
        - did
      properties:
        jobId:
          description: Id of an ongoing DID creation process.
          type: string
          example: 6d85bcd0-2ea3-4288-ab00-15afadd8a156
        did:
          description: DID to be deactivated.
          type: string
          example: did:didMethod1:WRfXPg8dantKVubE3HX8pw
        options:
          description: Options for the DID deactivate operation.
          type: object
        secret:
          description: >-
            Object with DID controller keys and other secrets needed for
            performing the DID deactivate operation.
          type: object
    DeactivateState:
      title: Deactivate DID result
      description: The state after a deactivate operation.
      type: object
      additionalProperties: false
      required:
        - didState
      properties:
        jobId:
          type: string
          example: 6d85bcd0-2ea3-4288-ab00-15afadd8a156
        didState:
          $ref: '#/components/schemas/DidState'
        didRegistrationMetadata:
          type: object
        didDocumentMetadata:
          type: object
    UpdateRequest:
      title: Update request object.
      description: Data object containing information to request update of DID.
      type: object
      additionalProperties: false
      required:
        - did
      properties:
        jobId:
          description: Id of an ongoing DID creation process.
          type: string
          example: 6d85bcd0-2ea3-4288-ab00-15afadd8a156
        did:
          description: DID to be updated.
          type: string
          example: did:didMethod1:WRfXPg8dantKVubE3HX8pw
        options:
          description: Options for the DID update operation.
          type: object
          additionalProperties: true
          properties:
            publicKey:
              description: Public key.
              type: string
            keyResponseMode:
              $ref: '#/components/schemas/keyResponseMode'
        secret:
          description: >-
            Object with DID controller keys and other secrets needed to perform
            the DID update operation.
          type: object
        didDocument:
          description: Partial or whole DID document
          type: object
        management:
          enum:
            - SERVER-MANAGED
            - USER-MANAGED
            - USER-CREATED
    UpdateState:
      title: Update state object.
      description: The state after an update operation.
      type: object
      additionalProperties: false
      required:
        - didState
      properties:
        jobId:
          type: string
          example: 6d85bcd0-2ea3-4288-ab00-15afadd8a156
        didState:
          $ref: '#/components/schemas/DidState'
        didRegistrationMetadata:
          type: object
        didDocumentMetadata:
          type: object
    keyResponseMode:
      title: Key response mode.
      description: The mode by which we determine which keys to reveal in the response.
      enum:
        - NONE
        - KEY_PAIR
        - PUBLIC_KEY_ONLY
    CreateRequest:
      title: Create request object
      description: Data object containing information to request creation of DID.
      type: object
      additionalProperties: false
      properties:
        jobId:
          description: Id of an ongoing DID creation process.
          type: string
          example: 6d85bcd0-2ea3-4288-ab00-15afadd8a156
        options:
          description: >-
            Options for the DID create operation, such as the network where the
            DID should be created
          type: object
          additionalProperties: true
          properties:
            publicKey:
              description: Public key.
              type: string
            keyResponseMode:
              $ref: '#/components/schemas/keyResponseMode'
          example:
            chain: testnet
        secret:
          description: >-
            Object with DID controller keys and other secrets needed for
            performing the DID create operation.
          type: object
          example:
            seed: 72WGp7NgFR1Oqdi8zlt7jQQ434XR0cNQ
        didDocument:
          description: Partial or complete DID document
          type: object
    CreateState:
      title: Create DID result
      description: The state after a create operation.
      type: object
      additionalProperties: false
      required:
        - didState
      properties:
        jobId:
          type: string
          example: 6d85bcd0-2ea3-4288-ab00-15afadd8a156
        didState:
          $ref: '#/components/schemas/DidState'
        didRegistrationMetadata:
          type: object
        didDocumentMetadata:
          type: object
    DidState:
      title: DID's current state
      description: The info object to describe the state of the DID.
      type: object
      additionalProperties: true
      properties:
        state:
          type: string
          example: finished
        did:
          type: string
          example: did:didMethod1:WRfXPg8dantKVubE3HX8pw
        secret:
          type: object
          example:
            keys:
              - privateKeyJwk:
                  kty: OKP
                  d: NzJXR3A3TmdGUjFPcWRpOHpsdDdqUVE0MzRYUjBjTlE
                  crv: Ed25519
                  x: jpIKKU2b77lNXKTNW2NGvw1GUMjU6v_l_tLJAH5uYz0
                publicKeyDIDURL: did:didMethod1:WRfXPg8dantKVubE3HX8pw#key-1