@i3m/wallet-desktop-openapi/src/paths/identities.yaml

i3M-Wallet Developers API that can be used to interact with the i3M-Wallet. In production it is encapsulated inside a secure connection. Please use the @i3m/wallet-protocol-api to interact with the wallet.

openapi: '3.0.3'

info:
  version: 1.0.0
  title: i3M Wallet API

paths:
  /identities/{did}/sign:
    post:
      summary: Signs a message
      operationId: identitySign
      x-eov-operation-handler: identities
      tags:
        - identities
      parameters:
        - in: path
          name: did
          schema:
            $ref: "../schema/identity.yaml#/components/schemas/did"
          required: true
      requestBody:
        description: Data to sign.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignInput"
      responses:
        "200":
          description: Signed data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignOutput"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "../schema/error.yaml#/components/schemas/ApiError"

  /identities/{did}/deploy-tx:
    post:
      summary: Signs and deploys a transaction
      operationId: identityDeployTransaction
      x-eov-operation-handler: identities
      tags:
        - identities
      parameters:
        - in: path
          name: did
          schema:
            $ref: "../schema/identity.yaml#/components/schemas/did"
          required: true
      requestBody:
        description: Transaction to sign and deploy
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Transaction"
      responses:
        "200":
          description: Selected identity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Receipt"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "../schema/error.yaml#/components/schemas/ApiError"

  /identities/{did}/info:
    get:
      summary: Gets extra information of an identity.
      operationId: identityInfo
      x-eov-operation-handler: identities
      tags:
        - identities
      parameters:
        - in: path
          name: did
          schema:
            $ref: "../schema/identity.yaml#/components/schemas/did"
          required: true
      responses:
        "200":
          description: Identity data
          content:
            application/json:
              schema:
                $ref: "../schema/identity.yaml#/components/schemas/IdentityData"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "../schema/error.yaml#/components/schemas/ApiError"


  /identities/select:
    get:
      summary: Gets an identity selected by the user.
      operationId: identitySelect
      x-eov-operation-handler: identities
      tags:
        - identities
      parameters:
        - in: query
          name: reason
          schema:
            type: string
            description: Message to show to the user with the reason to pick an identity
      responses:
        "200":
          description: Selected identity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentitySelectOutput"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "../schema/error.yaml#/components/schemas/ApiError"

  /identities:
    get:
      summary: List all DIDs
      operationId: identityList
      x-eov-operation-handler: identities
      tags:
        - identities
      parameters:
        - in: query
          name: alias
          schema:
            type: string
            description: An alias for the identity
      responses:
        "200":
          description: An array of identities
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentityListInput"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "../schema/error.yaml#/components/schemas/ApiError"

    post:
      summary: Create an account
      operationId: identityCreate
      x-eov-operation-handler: identities
      tags:
        - identities
      requestBody:
        description: Create a DID.
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IdentityCreateInput"
      responses:
        "201":
          description: the ID and type of the created account
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentityCreateOutput"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "../schema/error.yaml#/components/schemas/ApiError"

components:
  schemas:
    IdentitySelectOutput: 
      title: IdentitySelectOutput
      type: object
      properties:
        did:
          $ref: "../schema/identity.yaml#/components/schemas/did"
      required:
        - did

    SignInput:
      title: SignInput
      oneOf:
        - $ref: '#/components/schemas/SignTransaction'
        - $ref: '#/components/schemas/SignRaw'
        - $ref: '#/components/schemas/SignJWT'

    SignRaw:
      title: SignRaw
      type: object
      properties:
        type:
          $ref: '#/components/schemas/SignTypes'
          enum:
            - Raw
        data:
          type: object
          properties:
            payload:
              description: Base64Url encoded data to sign
              type: string
              pattern: ^[A-Za-z0-9_-]+$
          required:
            - payload
      required:
        - type
        - data


    SignTransaction:
      title: SignTransaction
      type: object
      properties:
        type:
          $ref: '#/components/schemas/SignTypes'
          enum:
            - Transaction
        data:
          $ref: '#/components/schemas/Transaction'
      required:
        - type
        - data
    
    SignJWT:
      title: SignJWT
      type: object
      properties:
        type:
          $ref: '#/components/schemas/SignTypes'
          enum:
            - JWT
        data:
          type: object
          properties:
            header: 
              description: header fields to be added to the JWS header. "alg" and "kid" will be ignored since they are automatically added by the wallet.
              type: object
              additionalProperties: true
            payload:
              description: A JSON object to be signed by the wallet. It will become the payload of the generated JWS. 'iss' (issuer) and 'iat' (issued at) will be automatically added by the wallet and will override provided values.
              type: object
              additionalProperties: true
          required:
            - payload
      required:
        - type
        - data

    Transaction:
      title: Transaction
      type: object
      additionalProperties: true
      properties:
        from:
          type: string
        to:
          type: string
        nonce:
          type: number

    SignOutput:
      title: SignOutput
      type: object
      properties:
        signature:
          type: string
      required:
        - signature

    Receipt:
      title: Receipt
      type: object
      properties:
        receipt:
          type: string
      required:
        - receipt

    SignTypes:
      title: SignTypes
      type: string
      enum:
        - Transaction
        - Raw
        - JWT

    IdentityListInput:
      title: IdentityListInput
      description: A list of DIDs
      type: array
      items:
        type: object
        properties:
          did:
            $ref: "../schema/identity.yaml#/components/schemas/did"
        required:
          - did

    IdentityCreateInput:
      title: IdentityCreateInput
      description: |
        Besides the here defined options, provider specific properties should be added here if necessary, e.g. "path" for BIP21 wallets, or the key algorithm (if the wallet supports multiple algorithm).
      type: object
      properties:
        alias:
          type: string
      additionalProperties: true
    
    IdentityCreateOutput:
      title: IdentityCreateOutput
      description: |
        It returns the account id and type
      type: object
      properties:
        did:
          $ref: "../schema/identity.yaml#/components/schemas/did"
      additionalProperties: true
      required:
        - did