swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector App API
schemes:
- https
tags:
- name: App
paths:
  /app/governance/constitution:
    get:
      operationId: microsoftAzureGetconstitution
      x-ms-examples:
        GetConstitution:
          $ref: ./examples/ledger/GetConstitution.json
      summary: Microsoft Azure Gets The Constitution Used For Governance
      description: The constitution is a script that assesses and applies proposals from consortium members.
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      responses:
        '200':
          description: The constitution.
          schema:
            $ref: '#/definitions/Constitution'
        default:
          description: Error response describing why the operation failed.
          schema:
            $ref: common.json#/definitions/ConfidentialLedgerError
      tags:
      - App
  /app/governance/members:
    get:
      operationId: microsoftAzureListconsortiummembers
      x-ms-examples:
        ListConsortiumMembers:
          $ref: ./examples/ledger/ListConsortiumMembers.json
      x-ms-pageable:
        itemName: members
        nextLinkName: nextLink
      summary: Microsoft Azure Lists The Consortium Members
      description: Consortium members can manage the Confidential Ledger.
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      responses:
        '200':
          description: List of consortium members.
          schema:
            $ref: '#/definitions/Consortium'
        default:
          description: Error response describing why the operation failed.
          schema:
            $ref: common.json#/definitions/ConfidentialLedgerError
      tags:
      - App
  /app/enclaveQuotes:
    get:
      operationId: microsoftAzureGetenclavequotes
      x-ms-examples:
        GetEnclaveQuotes:
          $ref: ./examples/ledger/GetEnclaveQuotes.json
      summary: Microsoft Azure Gets Quotes For All Nodes Of The Confidential Ledger
      description: A quote is an SGX enclave measurement that can be used to verify the validity of a node and its enclave.
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      responses:
        '200':
          description: Response containing enclave quotes.
          schema:
            $ref: '#/definitions/ConfidentialLedgerEnclaves'
        default:
          description: Error response describing why the operation failed
          schema:
            $ref: common.json#/definitions/ConfidentialLedgerError
      tags:
      - App
  /app/collections:
    get:
      operationId: microsoftAzureListcollections
      x-ms-examples:
        GetCollectionIds:
          $ref: ./examples/ledger/ListCollections.json
      x-ms-pageable:
        itemName: collections
        nextLinkName: nextLink
      summary: Microsoft Azure Retrieves A List Of Collection Ids Present In The Confidential Ledger
      description: Collection ids are user-created collections of ledger entries
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      responses:
        '200':
          description: List of collections
          schema:
            $ref: '#/definitions/PagedCollections'
        default:
          description: Error response describing why the operation failed
          schema:
            $ref: common.json#/definitions/ConfidentialLedgerError
      tags:
      - App
  /app/transactions:
    get:
      operationId: microsoftAzureListledgerentries
      x-ms-examples:
        ListLedgerEntries:
          $ref: ./examples/ledger/ListLedgerEntries.json
      x-ms-pageable:
        itemName: entries
        nextLinkName: nextLink
      summary: Microsoft Azure Gets Ledger Entries From A Collection Corresponding To A Range
      description: A collection id may optionally be specified. Only entries in the specified (or default) collection will be returned.
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      - $ref: '#/parameters/CollectionIdParameter'
      - $ref: '#/parameters/TransactionIdFromParameter'
      - $ref: '#/parameters/TransactionIdToParameter'
      responses:
        '200':
          description: Ledger entries in the specified range.
          schema:
            $ref: '#/definitions/PagedLedgerEntries'
        default:
          description: Error response describing why the operation failed
          schema:
            $ref: common.json#/definitions/ConfidentialLedgerError
      tags:
      - App
    post:
      operationId: microsoftAzureCreateledgerentry
      x-ms-examples:
        CreateLedgerEntry:
          $ref: ./examples/ledger/CreateLedgerEntry.json
      summary: Microsoft Azure Writes A Ledger Entry
      description: A collection id may optionally be specified.
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      - $ref: '#/parameters/CollectionIdParameter'
      - in: body
        name: entry
        description: Ledger entry.
        required: true
        schema:
          $ref: '#/definitions/LedgerEntry'
      responses:
        '200':
          description: Returns the transaction id at which the write will be durably stored.
          headers:
            x-ms-ccf-transaction-id:
              type: string
              description: The transaction id at which this write will become durable.
          schema:
            $ref: '#/definitions/LedgerWriteResult'
        default:
          description: Error response describing why the operation failed
          schema:
            $ref: common.json#/definitions/ConfidentialLedgerError
      tags:
      - App
  /app/transactions/{transactionId}:
    get:
      operationId: microsoftAzureGetledgerentry
      x-ms-examples:
        GetLedgerEntry:
          $ref: ./examples/ledger/GetLedgerEntry.json
      summary: Microsoft Azure Gets The Ledger Entry At The Specified Transaction Id A Collection Id May Optionally Be Specified To Indicate The Collection From Which To Fetch The Value
      description: To return older ledger entries, the relevant sections of the ledger must be read from disk and validated. To prevent blocking within the enclave, the response will indicate whether the entry is ready and part of the response, or if the loading is still ongoing.
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      - $ref: '#/parameters/CollectionIdParameter'
      - $ref: '#/parameters/TransactionIdParameter'
      responses:
        '200':
          description: The result of querying the Confidential Ledger.
          schema:
            $ref: '#/definitions/LedgerQueryResult'
        default:
          description: Error response describing why the operation failed.
          schema:
            $ref: common.json#/definitions/ConfidentialLedgerError
      tags:
      - App
  /app/transactions/{transactionId}/receipt:
    get:
      operationId: microsoftAzureGetreceipt
      x-ms-examples:
        GetReceipt:
          $ref: ./examples/ledger/GetReceipt.json
      summary: Microsoft Azure Gets A Receipt Certifying Ledger Contents At A Particular Transaction Id
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      - $ref: '#/parameters/TransactionIdParameter'
      responses:
        '200':
          description: The receipt for the write occurring at the transaction id.
          schema:
            $ref: '#/definitions/TransactionReceipt'
        default:
          description: Error response describing why the operation failed
          schema:
            $ref: common.json#/definitions/ConfidentialLedgerError
      description: Needs a more full description created.
      tags:
      - App
  /app/transactions/{transactionId}/status:
    get:
      operationId: microsoftAzureGettransactionstatus
      x-ms-examples:
        GetTransactionStatus:
          $ref: ./examples/ledger/GetTransactionStatus.json
      summary: Microsoft Azure Gets The Status Of An Entry Identified By A Transaction Id
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      - $ref: '#/parameters/TransactionIdParameter'
      responses:
        '200':
          description: The status of the entry recorded at the specified transaction id.
          schema:
            $ref: '#/definitions/TransactionStatus'
        default:
          description: Error response describing why the operation failed
          schema:
            $ref: common.json#/definitions/ConfidentialLedgerError
      description: Needs a more full description created.
      tags:
      - App
  /app/transactions/current:
    get:
      operationId: microsoftAzureGetcurrentledgerentry
      x-ms-examples:
        GetCurrentLedgerEntry:
          $ref: ./examples/ledger/GetCurrentLedgerEntry.json
      summary: Microsoft Azure Gets The Current Value Available In The Ledger
      description: A collection id may optionally be specified.
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      - $ref: '#/parameters/CollectionIdParameter'
      responses:
        '200':
          description: The current ledger entry available on the receiving node. Non-primary nodes may return older values.
          schema:
            $ref: '#/definitions/LedgerEntry'
        default:
          description: Error response describing why the operation failed
          schema:
            $ref: common.json#/definitions/ConfidentialLedgerError
      tags:
      - App
  /app/users/{userId}:
    delete:
      operationId: microsoftAzureDeleteuser
      x-ms-examples:
        DeleteUser:
          $ref: ./examples/ledger/DeleteUser.json
      summary: Microsoft Azure Deletes A User From The Confidential Ledger
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      - $ref: '#/parameters/UserIdParameter'
      responses:
        '204':
          description: The specified user is deleted.
        default:
          description: Error response describing why the operation failed
          schema:
            $ref: common.json#/definitions/ConfidentialLedgerError
      description: Needs a more full description created.
      tags:
      - App
    get:
      operationId: microsoftAzureGetuser
      x-ms-examples:
        GetUser:
          $ref: ./examples/ledger/GetUser.json
      summary: Microsoft Azure Gets A User
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      - $ref: '#/parameters/UserIdParameter'
      responses:
        '200':
          description: Details about the specified user.
          schema:
            $ref: '#/definitions/LedgerUser'
        default:
          description: Error response describing why the operation failed
          schema:
            $ref: common.json#/definitions/ConfidentialLedgerError
      description: Needs a more full description created.
      tags:
      - App
    patch:
      operationId: microsoftAzureCreateorupdateuser
      x-ms-examples:
        CreateOrUpdateUser:
          $ref: ./examples/ledger/CreateOrUpdateUser.json
      summary: Microsoft Azure Adds A User Or Updates A User S Fields
      description: A JSON merge patch is applied for existing users
      consumes:
      - application/merge-patch+json
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      - $ref: '#/parameters/UserIdParameter'
      - $ref: '#/parameters/UserDetailsParameter'
      responses:
        '200':
          description: User created or updated successfully.
          schema:
            $ref: '#/definitions/LedgerUser'
        default:
          description: Error response describing why the operation failed
          schema:
            $ref: common.json#/definitions/ConfidentialLedgerError
      tags:
      - App
definitions:
  LedgerUser:
    description: Details about a Confidential Ledger user.
    required:
    - assignedRole
    properties:
      assignedRole:
        $ref: '#/definitions/LedgerUserRole'
      userId:
        $ref: '#/definitions/UserId'
        readOnly: true
    type: object
  PemArray:
    items:
      $ref: '#/definitions/Pem'
    type: array
  TransactionState:
    type: string
    description: Represents the state of the transaction.
    enum:
    - Committed
    - Pending
    x-ms-enum:
      name: TransactionState
      modelAsString: true
  LedgerEntries:
    description: Array of ledger entries.
    type: array
    items:
      $ref: '#/definitions/LedgerEntry'
  ReceiptElementArray:
    items:
      $ref: '#/definitions/ReceiptElement'
    type: array
  LedgerEntryClaim:
    description: An application claim derived from ledger entry data.
    required:
    - protocol
    properties:
      collectionId:
        description: Identifier of a collection.
        type: string
      contents:
        description: Contents of a ledger entry.
        type: string
      secretKey:
        type: string
        description: Base64-encoded secret key.
      protocol:
        $ref: '#/definitions/ApplicationClaimProtocol'
    type: object
  PagedCollections:
    description: Paginated collections returned in response to a query.
    type: object
    required:
    - collections
    properties:
      collections:
        items:
          $ref: '#/definitions/Collection'
        type: array
      nextLink:
        description: Path from which to retrieve the next page of results.
        type: string
  TransactionId:
    description: A unique identifier for the state of the ledger. If returned as part of a LedgerEntry, it indicates the state from which the entry was read.
    type: string
  ReceiptContents:
    properties:
      cert:
        type: string
      leaf:
        type: string
      leafComponents:
        $ref: '#/definitions/ReceiptLeafComponents'
      nodeId:
        type: string
      proof:
        $ref: '#/definitions/ReceiptElementArray'
      root:
        type: string
      serviceEndorsements:
        $ref: '#/definitions/PemArray'
      signature:
        type: string
    required:
    - signature
    - proof
    - nodeId
    type: object
  ConsortiumMember:
    description: Describes a member of the consortium.
    required:
    - certificate
    - id
    properties:
      certificate:
        type: string
        description: PEM-encoded certificate associated with the member.
      id:
        description: Identifier assigned to the member.
        $ref: '#/definitions/EntityId'
    type: object
  EnclaveQuote:
    description: Contains the enclave quote.
    required:
    - nodeId
    - quoteVersion
    - raw
    properties:
      nodeId:
        description: ID assigned to this node.
        $ref: '#/definitions/EntityId'
      mrenclave:
        description: MRENCLAVE value of the code running in the enclave.
        type: string
      quoteVersion:
        description: Version of the quote presented.
        type: string
      raw:
        description: Raw SGX quote, parsable by tools like Open Enclave's oeverify.
        type: string
    type: object
  ApplicationClaims:
    description: List of application claims.
    type: array
    items:
      $ref: '#/definitions/ApplicationClaim'
  EntityId:
    description: Identifier for an entity.
    type: string
  TransactionStatus:
    description: Response returned to a query for the transaction status
    required:
    - state
    - transactionId
    properties:
      state:
        $ref: '#/definitions/TransactionState'
      transactionId:
        $ref: '#/definitions/TransactionId'
    type: object
  EnclaveQuotes:
    description: Dictionary of enclave quotes, indexed by node id.
    additionalProperties:
      $ref: '#/definitions/EnclaveQuote'
    type: object
  LedgerQueryResult:
    description: The result of querying for a ledger entry from an older transaction id. The ledger entry is available in the response only if the returned state is Ready.
    required:
    - state
    properties:
      state:
        $ref: '#/definitions/LedgerQueryState'
      entry:
        description: The ledger entry found as a result of the query. This is only available if the query is in Ready state.
        $ref: '#/definitions/LedgerEntry'
    type: object
  TransactionReceipt:
    description: A receipt certifying the transaction at the specified id.
    required:
    - state
    - transactionId
    properties:
      applicationClaims:
        $ref: '#/definitions/ApplicationClaims'
      receipt:
        $ref: '#/definitions/ReceiptContents'
      state:
        $ref: '#/definitions/LedgerQueryState'
      transactionId:
        $ref: '#/definitions/TransactionId'
    type: object
  ApplicationClaimProtocol:
    type: string
    description: Represents the protocol to be used to compute the digest of a claim from the given claim data.
    enum:
    - LedgerEntryV1
    x-ms-enum:
      name: ApplicationClaimProtocol
      modelAsString: true
  LedgerEntry:
    description: An entry in the ledger.
    required:
    - contents
    properties:
      contents:
        type: string
        description: Contents of the ledger entry.
      collectionId:
        type: string
        readOnly: true
      transactionId:
        $ref: '#/definitions/TransactionId'
        readOnly: true
    type: object
  ReceiptElement:
    properties:
      left:
        type: string
      right:
        type: string
    type: object
  PagedLedgerEntries:
    description: Paginated ledger entries returned in response to a query.
    type: object
    required:
    - state
    - entries
    properties:
      state:
        $ref: '#/definitions/LedgerQueryState'
      nextLink:
        description: Path from which to retrieve the next page of results.
        type: string
      entries:
        $ref: '#/definitions/LedgerEntries'
  LedgerWriteResult:
    description: Returned as a result of a write to the Confidential Ledger, the transaction id in the response indicates when the write will become durable.
    required:
    - collectionId
    properties:
      collectionId:
        type: string
    type: object
  Pem:
    type: string
  Consortium:
    description: List of members in the consortium.
    required:
    - members
    properties:
      members:
        type: array
        items:
          $ref: '#/definitions/ConsortiumMember'
      nextLink:
        description: Path from which to retrieve the next page of results.
        type: string
    type: object
  ConfidentialLedgerEnclaves:
    description: Information about the enclaves running the Confidential Ledger.
    required:
    - currentNodeId
    - enclaveQuotes
    properties:
      currentNodeId:
        description: Id of the Confidential Ledger node responding to the request.
        $ref: '#/definitions/EntityId'
      enclaveQuotes:
        $ref: '#/definitions/EnclaveQuotes'
    type: object
  Constitution:
    description: The governance script for the application.
    required:
    - digest
    - script
    properties:
      digest:
        description: SHA256 digest of the constitution script.
        type: string
      script:
        description: Contents of the constitution.
        type: string
    type: object
  ReceiptLeafComponents:
    properties:
      claimsDigest:
        type: string
      commitEvidence:
        type: string
      writeSetDigest:
        type: string
    type: object
  LedgerUserRole:
    type: string
    description: Represents an assignable role.
    enum:
    - Administrator
    - Contributor
    - Reader
    x-ms-enum:
      name: ConfidentialLedgerUserRoleName
      modelAsString: true
  ApplicationClaim:
    description: A claim of a ledger application.
    required:
    - kind
    properties:
      digest:
        $ref: '#/definitions/ClaimDigest'
      kind:
        $ref: '#/definitions/ApplicationClaimKind'
      ledgerEntry:
        $ref: '#/definitions/LedgerEntryClaim'
    type: object
  LedgerQueryState:
    description: State of a ledger query.
    type: string
    enum:
    - Loading
    - Ready
    x-ms-enum:
      name: ConfidentialLedgerQueryState
      modelAsString: true
  UserId:
    description: Identifier for the user. This must either be an AAD object id or a certificate fingerprint.
    type: string
  ClaimDigest:
    description: An application claim in digested form.
    required:
    - protocol
    properties:
      value:
        type: string
        description: The digest of the application claim, in hexadecimal form.
      protocol:
        $ref: '#/definitions/ApplicationClaimProtocol'
    type: object
  ApplicationClaimKind:
    type: string
    description: Represents the kind of an application claim.
    enum:
    - LedgerEntry
    - ClaimDigest
    x-ms-enum:
      name: ApplicationClaimKind
      modelAsString: true
  Collection:
    description: Identifier for collections.
    required:
    - collectionId
    properties:
      collectionId:
        type: string
    type: object
parameters:
  UserDetailsParameter:
    name: userDetails
    description: Details about a Confidential Ledger user.
    in: body
    required: true
    x-ms-parameter-location: method
    schema:
      $ref: '#/definitions/LedgerUser'
  UserIdParameter:
    name: userId
    in: path
    required: true
    description: The user id, either an AAD object ID or certificate fingerprint.
    type: string
    x-ms-parameter-location: method
    x-ms-skip-url-encoding: true
  TransactionIdToParameter:
    name: toTransactionId
    in: query
    required: false
    x-ms-parameter-location: method
    description: Specify the last transaction ID in a range.
    type: string
  CollectionIdParameter:
    name: collectionId
    in: query
    required: false
    x-ms-parameter-location: method
    description: The collection id.
    type: string
  TransactionIdParameter:
    name: transactionId
    in: path
    required: true
    x-ms-parameter-location: method
    description: Identifies a write transaction.
    type: string
  TransactionIdFromParameter:
    name: fromTransactionId
    in: query
    required: false
    x-ms-parameter-location: method
    description: Specify the first transaction ID in a range.
    type: string
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'