openapi.yaml

openapi: 3.1.0
servers:
  - url: "/1.0/"
info:
  title: Universal Registrar
  description: Universal Registrar
  version: 1.0.1
  contact:
    name: Decentralized Identity Foundation
    email: markus@danubetech.com
paths:
  "/create":
    post:
      summary: Create a DID
      description: <p>This endpoint creates a DID. As input it takes the DID, a DID
        document, plus optional DID registration <a href="https://identity.foundation/did-registration/#options">options</a>
        and <a href="https://identity.foundation/did-registration/#secret">secrets</a>
        needed to create a DID. The output is a state object that represents the current
        state of the DID creation process.</p> <p>See the <a href="https://identity.foundation/did-registration/#create">DID
        Registration</a> specification for additional details.</p>
      operationId: create
      tags:
        - Universal Registrar
      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:
      summary: Update a DID
      description: <p>This endpoint updates a DID. As input it takes the existing
        DID, a DID document, plus optional DID registration <a href="https://identity.foundation/did-registration/#options">options</a>
        and <a href="https://identity.foundation/did-registration/#secret">secrets</a>
        needed to update a DID. The output is a state object that represents the current
        state of the DID update process.</p> <p>See the <a href="https://identity.foundation/did-registration/#update">DID
        Registration</a> specification for additional details.</p>
      operationId: update
      tags:
        - Universal Registrar
      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:
      summary: Deactivate a DID
      description: <p>This endpoint deactivates a DID. As input it takes the existing
        DID, plus optional DID registration <a href="https://identity.foundation/did-registration/#options">options</a>
        and <a href="https://identity.foundation/did-registration/#secret">secrets</a>
        needed to deactivate a DID. The output is a state object that represents the
        current state of the DID deactivation process.</p> <p>See the <a href="https://identity.foundation/did-registration/#deactivate">DID
        Registration</a> specification for additional details.</p>
      operationId: deactivate
      tags:
        - Universal Registrar
      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: Return a map of configuration properties
      description: <p>This endpoint returns a map of the configuration properties
        of the DID Registrar, including of its drivers.</p>
      operationId: universalRegistrarGetProperties
      tags:
        - Universal Registrar
      responses:
        "200":
          description: Success.
          content:
            application/did+json:
              schema:
                type: object
                description: A map of properties.
  "/methods":
    get:
      summary: Return a list of supported DID methods
      description: <p>This endpoint returns a list of DID methods supported by the
        DID Registrar.</p>
      operationId: universalRegistrarGetMethods
      tags:
        - Universal Registrar
      responses:
        "200":
          description: Success.
          content:
            application/did+json:
              schema:
                type: array
                items:
                  type: string
                description: The list of supported DID methods.
                example:
                  - indy
                  - ebsi
                  - ion
                  - cheqd
                  - key
components:
  schemas:
    RegistrarRequest:
      description: Input fields for a DID operation.
      type: object
      properties:
        jobId:
          description: This input field is used to keep track of an ongoing DID operation
            process. See <a href="https://identity.foundation/did-registration/#jobid">https://identity.foundation/did-registration/#jobid</a>.
          type: string
          example: 6d85bcd0-2ea3-4288-ab00-15afadd8a156
        options:
          $ref: "#/components/schemas/RequestOptions"
        secret:
          $ref: "#/components/schemas/RequestSecret"
    RequestOptions:
      description: This input field contains an object with various options for
        the DID operation, such as the network where the DID operation should be executed.
        See <a href="https://identity.foundation/did-registration/#options">https://identity.foundation/did-registration/#options</a>.
      type: object
      properties:
        clientSecretMode:
          $ref: "#/components/schemas/Boolean"
        storeSecrets:
          $ref: "#/components/schemas/Boolean"
        returnSecrets:
          $ref: "#/components/schemas/Boolean"
        requestVerificationMethod:
          $ref: "#/components/schemas/RequestOptionsRequestVerificationMethod"
      additionalProperties: { }
      example:
        network: testnet
    RequestOptionsRequestVerificationMethod:
      type: array
      items:
        $ref: "#/components/schemas/VerificationMethodTemplate"
    CreateRequest:
      description: Input fields for a DID create operation.
      allOf:
        - $ref: "#/components/schemas/RegistrarRequest"
        - type: object
          properties:
            didDocument:
              description: This input field contains the DID document to be used for the DID create operation. See
                <a href="https://identity.foundation/did-registration/#diddocument">https://identity.foundation/did-registration/#diddocument</a>.
              $ref: "#/components/schemas/DidDocument"
    UpdateRequest:
      description: Input fields for a DID update operation.
      allOf:
        - $ref: "#/components/schemas/RegistrarRequest"
        - type: object
          required:
            - did
          properties:
            did:
              description: This input field indicates the DID that is the target of the
                DID update operation.
              type: string
              example: did:indy:sovrin:WRfXPg8dantKVubE3HX8pw
            didDocumentOperation:
              description: This input field indicates which update operation should be
                applied to a DID’s associated DID document. See <a href="https://identity.foundation/did-registration/#diddocumentoperation">https://identity.foundation/did-registration/#diddocumentoperation</a>.
              type: array
              items:
                type: string
              example:
                - setDidDocument
            didDocument:
              description: This input field contains either a complete DID document, or
                an incremental change (diff) to a DID document. See <a href="https://identity.foundation/did-registration/#diddocument">https://identity.foundation/did-registration/#diddocument</a>.
              type: array
              items:
                $ref: "#/components/schemas/DidDocument"
    DeactivateRequest:
      description: Input fields for a DID deactivate operation.
      allOf:
        - $ref: "#/components/schemas/RegistrarRequest"
        - type: object
          required:
            - did
          properties:
            did:
              description: This input field indicates the DID that is the target of the
                DID deactivation operation.
              type: string
              example: did:indy:sovrin:WRfXPg8dantKVubE3HX8pw
    DidDocument:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/String"
          example: did:indy:sovrin:WRfXPg8dantKVubE3HX8pw
        controller:
          $ref: "#/components/schemas/DidDocumentController"
          example: ['did:indy:sovrin:WRfXPg8dantKVubE3HX8pw']
        verificationMethod:
          $ref: "#/components/schemas/DidDocumentVerificationMethod"
        service:
          $ref: "#/components/schemas/DidDocumentService"
      additionalProperties: { }
    DidDocumentController:
      type: array
      items:
        type: string
    DidDocumentVerificationMethod:
      type: array
      items:
        type: object
        additionalProperties: { }
    DidDocumentService:
      type: array
      items:
        type: object
        additionalProperties: { }
    RegistrarState:
      description: The state after a DID operation.
      type: object
      required:
        - didState
      properties:
        jobId:
          type: string
          example: 6d85bcd0-2ea3-4288-ab00-15afadd8a156
        didState:
          $ref: "#/components/schemas/DidState"
        didRegistrationMetadata:
          type: object
          additionalProperties: { }
        didDocumentMetadata:
          type: object
          additionalProperties: { }
    CreateState:
      description: The state after a DID create operation.
      allOf:
        - $ref: "#/components/schemas/RegistrarState"
        - type: object
    UpdateState:
      description: The state after an update operation.
      allOf:
        - $ref: "#/components/schemas/RegistrarState"
        - type: object
    DeactivateState:
      description: The state after a deactivate operation.
      allOf:
        - $ref: "#/components/schemas/RegistrarState"
        - type: object
    DidState:
      description: The current state of a DID.
      type: object
      required:
        - state
      discriminator:
        propertyName: state
        mapping:
          finished: "#/components/schemas/DidStateFinished"
          failed: "#/components/schemas/DidStateFailed"
          action: "#/components/schemas/DidStateAction"
          wait: "#/components/schemas/DidStateWait"
      properties:
        state:
          $ref: "#/components/schemas/String"
          example: finished
        did:
          $ref: "#/components/schemas/String"
          example: did:indy:sovrin:WRfXPg8dantKVubE3HX8pw
        secret:
          $ref: "#/components/schemas/DidStateSecret"
        didDocument:
          $ref: "#/components/schemas/DidDocument"
      additionalProperties: { }
    DidStateFinished:
      description: This state indicates that the DID operation has been completed. See
        https://identity.foundation/did-registration/#didstatestatefinished.
      allOf:
        - $ref: "#/components/schemas/DidState"
        - type: object
    DidStateFailed:
      description: This state indicates that the DID operation has failed. See
        https://identity.foundation/did-registration/#didstatestatefailed.
      allOf:
        - $ref: "#/components/schemas/DidState"
        - type: object
          properties:
            error:
              type: string
            reason:
              type: string
    DidStateAction:
      description: This state indicates that the client needs to perform an action, before the DID operation can be continued. See
        https://identity.foundation/did-registration/#didstatestateaction.
      allOf:
        - $ref: "#/components/schemas/DidState"
        - type: object
          properties:
            action:
              type: string
            verificationMethodTemplate:
              type: array
              items:
                $ref: "#/components/schemas/VerificationMethodTemplate"
            signingRequest:
              type: [object, null]
              additionalProperties:
                $ref: "#/components/schemas/SigningRequest"
            decryptionRequest:
              type: [object, null]
              additionalProperties:
                $ref: "#/components/schemas/DecryptionRequest"
    DidStateWait:
      description: This state indicates that the client needs to wait, before the DID operation can be continued.
        See https://identity.foundation/did-registration/#didstatestatewait.
      allOf:
        - $ref: "#/components/schemas/DidState"
        - type: object
          properties:
            wait:
              type: string
            waittime:
              type: string
    Secret:
      description: Secrets in requests and states.
      type: object
      properties:
        verificationMethod:
          $ref: "#/components/schemas/SecretVerificationMethod"
      additionalProperties: { }
      example:
        verificationMethod:
          - id: did:indy:sovrin:WRfXPg8dantKVubE3HX8pw#key-1
            type: JsonWebKey2020
            privateKeyJwk:
              kty: OKP
              crv: Ed25519
              d: NzJXR3A3TmdGUjFPcWRpOHpsdDdqUVE0MzRYUjBjTlE
              x: jpIKKU2b77lNXKTNW2NGvw1GUMjU6v_l_tLJAH5uYz0
    SecretVerificationMethod:
      type: array
      items:
        oneOf:
          - $ref: "#/components/schemas/VerificationMethodPublicData"
          - $ref: "#/components/schemas/VerificationMethodPrivateData"
          - $ref: "#/components/schemas/SecretVerificationMethodVerificationMethodTemplate"
    SecretVerificationMethodVerificationMethodTemplate:
      type: array
      items:
         $ref: "#/components/schemas/VerificationMethodTemplate"
    RequestSecret:
      description: This input field contains an object with DID controller keys
        and other secrets needed for performing the DID operation. See
        https://identity.foundation/did-registration/#secret.
      allOf:
        - $ref: "#/components/schemas/Secret"
        - type: object
          properties:
            signingResponse:
              type: [object, null]
              additionalProperties:
                $ref: "#/components/schemas/SigningResponse"
            decryptionResponse:
              type: [object, null]
              additionalProperties:
                $ref: "#/components/schemas/DecryptionResponse"
          example:
            seed: 72WGp7NgFR1Oqdi8zlt7jQQ434XR0cNQ
    DidStateSecret:
      description: This output field contains an object with DID controller keys and other secrets. See
        https://identity.foundation/did-registration/#didstatesecret.
      allOf:
        - $ref: "#/components/schemas/Secret"
        - type: object
          example:
            seed: 72WGp7NgFR1Oqdi8zlt7jQQ434XR0cNQ
    SigningRequest:
      description: A signing request, see https://identity.foundation/did-registration/#signing-request-set.
      type: object
      required:
        - serializedPayload
        - alg
      properties:
        payload:
          type: object
        serializedPayload:
          $ref: "#/components/schemas/String"
        kid:
          $ref: "#/components/schemas/String"
        alg:
          $ref: "#/components/schemas/String"
        purpose:
          $ref: "#/components/schemas/String"
      additionalProperties: { }
    SigningRequestSet:
      description: A signing request set, see https://identity.foundation/did-registration/#signing-request-set.
      type: object
      additionalProperties:
        $ref: "#/components/schemas/SigningRequest"
    SigningResponse:
      description: A signing response, see https://identity.foundation/did-registration/#signing-response-set.
      type: object
      required:
        - signature
      properties:
        signature:
          $ref: "#/components/schemas/String"
        kid:
          $ref: "#/components/schemas/String"
        alg:
          $ref: "#/components/schemas/String"
        purpose:
          $ref: "#/components/schemas/String"
      additionalProperties: { }
    SigningResponseSet:
      description: A signing response set, see https://identity.foundation/did-registration/#signing-response-set.
      type: object
      additionalProperties:
        $ref: "#/components/schemas/SigningResponse"
    DecryptionRequest:
      description: A decryption request, see https://identity.foundation/did-registration/#decryption-request-set.
      type: object
      required:
        - encryptedPayload
        - enc
      properties:
        payload:
          $ref: "#/components/schemas/String"
        encryptedPayload:
          $ref: "#/components/schemas/String"
        kid:
          $ref: "#/components/schemas/String"
        enc:
          $ref: "#/components/schemas/String"
        purpose:
          $ref: "#/components/schemas/String"
      additionalProperties: { }
    DecryptionRequestSet:
      description: A decryption request set, see https://identity.foundation/did-registration/#decryption-request-set.
      type: object
      additionalProperties:
        $ref: "#/components/schemas/DecryptionRequest"
    DecryptionResponse:
      description: A decryption response, see https://identity.foundation/did-registration/#decryption-response-set.
      type: object
      required:
        - decryptedPayload
      properties:
        decryptedPayload:
          $ref: "#/components/schemas/String"
        kid:
          $ref: "#/components/schemas/String"
        enc:
          $ref: "#/components/schemas/String"
        purpose:
          $ref: "#/components/schemas/String"
      additionalProperties: { }
    DecryptionResponseSet:
      description: A decryption response set, see https://identity.foundation/did-registration/#decryption-response-set.
      type: object
      additionalProperties:
        $ref: "#/components/schemas/DecryptionResponse"
    VerificationMethodData:
      type: object
      required:
        - type
      properties:
        id:
          type: string
        type:
          type: string
        controller:
          type: string
        purpose:
          type: array
          items:
            type: string
    VerificationMethodPublicData:
      description: A verification method public data object, see https://identity.foundation/did-registration/#verification-method-public-data
      allOf:
        - $ref: "#/components/schemas/VerificationMethodData"
        - type: object
          properties:
            publicKeyJwk:
              type: [object, null]
              additionalProperties: { }
            publicKeyMultibase:
              type: string
    VerificationMethodPrivateData:
      description: A verification method private data object, see https://identity.foundation/did-registration/#verification-method-private-data
      allOf:
        - $ref: "#/components/schemas/VerificationMethodData"
        - type: object
          properties:
            privateKeyJwk:
              type: [object, null]
              additionalProperties: { }
            privateKeyMultibase:
              type: string
    VerificationMethodTemplate:
      description: A verification method template, see https://identity.foundation/did-registration/#verification-method-template
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        controller:
          type: string
        purpose:
          type: array
          items:
            type: string
        publicKeyJwk:
          type: [object, null]
          additionalProperties: { }
    String:
      type: string
    Boolean:
      type: boolean