openapi: "3.0.0"
info:
  version: 1.0.1-SNAPSHOT
  title: Swagger for Enterprise STIR/SHAKEN
  license:
    name: 'Proprietary, subject to specific license agreements'
  description: "Covers the REST API definitions to be used to integrate the DLT to the Enterprise STIR/SHAKEN solution with verifiable credentials and DIDs"
servers:
  - url: https://localhost/v1

paths:
  /accounts:
    post:
      summary: Create an account for an organization/brand, a TNR/TNSP, a BPO, or a KYC Vetter.
      description: Create an account for an organization/brand, a TNR/TNSP, a BPO, or a KYC Vetter.  This will generate a seed and a Key Pair.  These will be stored in a secure fashion by the DLT Integration API.  The DID will be returned in the response payload and will be used to identify the organization going forward in both the integration API and in the DLT
      operationId: createAccount
      tags:
        - Accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountPostRequest"
      responses:
        '201':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountResponse"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /accounts/{orgIdParam}:
    get:
      summary: Retrieve account information from the Enterprise Identity DL Network, based on the DID/UUID for the account.
      operationId: getAccount
      tags:
        - Accounts
      parameters:
        - $ref: '#/components/parameters/orgIdParam'
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountResponse"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /vetterAuthorization/{orgIdParam}/vetter/{vetterIdParam}:
    post:
      summary: Allows an vetter to add the vetted organization data to the DLT
      operationId: createVettedorganizationOnDLT
      tags:
        - Vetter
      parameters:
        - $ref: '#/components/parameters/orgIdParam'
        - $ref: '#/components/parameters/vetterIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VetterRequestBody"
      responses:
        '201':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/vetterAuthorization"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /vetterAuthorization/{orgIdParam}/history/{historyStatus}:
    get:
      summary: Retrieve the vetter Authorization history for a given organization.
      operationId: getvetterAuthorizationHistory
      tags:
        - Vetter
      parameters:
        - $ref: '#/components/parameters/orgIdParam'
        - $ref: '#/components/parameters/historyStatus'
      responses:
        '201':
          description: Returns Vetted Organization Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/vetterAuthorizationList"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /tnAuthorization:
    post:
      summary: Allows an organization to allocate a TN to the DLT for another organization
      operationId: tnAuthorization
      tags:
        - tnAuthorization
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TNAuthorizationList'
      responses:
        '201':
          description: Return the newly created TNAuthorizationList
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TNAuthorizationResponseList'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /callerVerification/{orgIdParam}/tn/{tnIdParam}:
    get:
      summary: Retrieve the verification
      operationId: callerVerification
      tags:
        - callerVerification
      parameters:
        - $ref: '#/components/parameters/orgIdParam'
        - $ref: '#/components/parameters/tnIdParam'
      responses:
        '201':
          description: Returns Verification Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/callerVerificationResponse"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
components:
  parameters:
    orgIdParam:
      name: orgIdParam
      in: path
      required: true
      description: The DID/UUID of the organization
      schema:
        type: string
    vetterIdParam:
      name: vetterIdParam
      in: path
      required: true
      description: The DID of the vetter
      schema:
        type: string
    historyStatus:
      name: historyStatus
      in: path
      required: true
      description: Type of status response . 0 - Current, 1 - History
      schema:
        type: integer
        format: int32
    tnIdParam:
      name: tnIdParam
      in: path
      required: true
      description: Identifier for Telephone Number
      schema:
        type: string
  schemas:
    AccountPostRequest:
      description: Input to create a given organization
      type: object
      required:
        - name
        - type
      properties:
        did:
          type: string
          description: The DID/UUID of the account. This is assigned during the creation (POST) process and should be left blank for POSTs.
        name:
          type: string
        type:
          description: Type of organization. 0 - KYC Vetter, 1 - TNR, 2 - Brand, 3 – BPO, 4 – TNSP, 5 – CSP, 6 - TA
          type: integer
          format: int32
        
    AccountResponse:
      description: An account to represent a given organization
      type: object
      properties:
        did:
          description: Digital distributed identity of the account.  This is assigned during the creation (POST) process.  This is used going forward to identify the organization.
          type: string
        name:
          type: string
        type:
          description: Type of organization. 0 - KYC Vetter, 1 - TNR, 2 - Brand, 3 - BPO, 4- TNSP, 5-CSP, 6-TA
          type: integer
          format: int32
        privateKey:
          description: The private key generated for this account by the DLT integration API.
          type: string
        didDocument:
          $ref: "#/components/schemas/DidDocument"  
        createdTS:
          description: Time that this account was created in UTC milliseconds from EPOCH
          type: string
          format: date-time
        updatedTS:
          description: Time that this account was last updated in UTC milliseconds from EPOCH
          type: string
          format: date-time
    vetterAuthorization:
      type: object
      required:
        - organization
        - vetter
        - status
      properties:
        organization:
          $ref: "#/components/schemas/AccountResponse"
        vetter:
          $ref: "#/components/schemas/AccountResponse"
        status:
          description: Status of the vetting process.  0 - In Progress, 1 - Complete
          type: integer
          format: int32
        result:
          description: Result of the vetting process.  0 - Authorised, 1 - Not Authorised, 2 - Revoked
          type: integer
          format: int32
        vettedTS:
          description: Time that this Authorization became effective
          type: string
          format: date-time
        version:
          description: In the case that an Authorization is updated on the ledger, we will update the version. This will help to identify and order related Authorizations.
          type: integer
          format: int32
    vetterHistory:
      type: object
      required:
        - organization
        - vetter
        - status
      properties:
        vetter:
          $ref: "#/components/schemas/AccountResponse"
        status:
          description: Status of the vetting process.  0 - In Progress, 1 - Complete
          type: integer
          format: int32
        result:
          description: Result of the vetting process.  0 - Authorised, 1 - Not Authorised, 2 - Revoked
          type: integer
          format: int32
        vettedTS:
          description: Time that this Authorization became effective
          type: string
          format: date-time
        version:
          description: In the case that an Authorization is updated on the ledger, we will update the version. This will help to identify and order related Authorizations.
          type: integer
          format: int32
    vetterAuthorizationList:
      type: object
      required: 
        - organization
        - vetterAuthorizationList
      properties:
        organization:
          $ref: "#/components/schemas/AccountResponse"
        vetterAuthorizationList:
          type: array
          items:
            $ref: "#/components/schemas/vetterHistory"
    TNAuthorization:
      type: object
      required:
        - issuerDID
        - subjectDID
        - authorizationStartDate
        - authorizationEndDate
        - intendedUseOfAuthorization
        - authorizationType
      properties:
        tnId:
          description: Identifier of the telephone number.
          type: string
        issuerDID:
          description: DID of the organization that is allocating the TN.  This is likely the DID of the Issuer.
          type: string
        subjectDID:
          description: DID of the organization that the TN is being allocated to. This is likely the DID of the Subject.
          type: string
        intendedUseOfAuthorization:
          description: Text field tht allows you to specify the intended purpose the TNs in the Authorization will be used for.
          type: string
        tnIdType:
          description: Type of telephone number identifier. (0-E.164, 1-UUID, 2-DID, 3-Verifiable Credential).  This field will allow us some flexibility as we grow the solution to allow different types of identifiers for TNs.
          type: integer
          format: int32
        authorizationType:  
          description: The type of TN authorization, either "Allocation", “Assignment” or “Delegation”.
          type: string
        authorizationStartDate:
          description: Time that this TN Authorization becomes a valid Authorization.  Must be a future date.
          type: string
          format: date-time
        authorizationEndDate:
          description: Time that this TN Authorization will be revoked.  Must be a future date.  If this is not specified, it is assumed there is no end date
          type: string
          format: date-time
    TNAuthorizationResponse:
      type: object
      allOf:
        - $ref: "#/components/schemas/TNAuthorization"
      properties:
        verifiableCredential:
          $ref: "#/components/schemas/VerifiableCredential"
    TNAuthorizationList:
      type: object
      properties:
        tnAuthorization:
          type: array
          items:
            $ref: "#/components/schemas/TNAuthorization"
    TNAuthorizationResponseList:
      type: object
      properties:
        tnAuthorizationResponse:
          type: array
          items:
            $ref: "#/components/schemas/TNAuthorizationResponse"
    VetterRequestBody:
      type: object
      properties:
        status:
          type: string
        result:
          type: integer
          format: int32
        vettedTS:
          type: string
          format: date-time
          description: Time that this authorization became effective
        version:
          type: integer
          format: int32
          description: In the case that an authorization is updated on the ledger, we will update the version. This will help to identify and order related authorizations.
        
        
    VerifiableCredential:
      description: "We pulled this schema from: https://www.w3.org/TR/vc-data-model/#example-1-a-simple-example-of-a-verifiable-credential as a group we will want to agree on what these look like or at least what is required"
      type: object
      properties:
        "@context":
          description: Sets the context, which establishes the special terms we will use like issuer and alumniOf
          type: array
          items:
            type: string
        id:
          description: Identifier for the credential
          type: string
        type:
          description: Crediential types, which declare what data to expect in the credential
          type: array
          items:
            type: string
        issuer:
          description: Entity that issued the credential
          type: string
        issuanceDate:
          description: Time that this verifiable credential was issued
          type: string
          format: date-time
        credentialSubject:
          description: Claims about the subjects of the credential
          type: object
          properties:
            id:
              description: Identifier about the only subject of the credential
              type: string
            alumniOf:
              type: object
              properties:
                id:
                  type: string
                name:
                  type: array
                  items:
                    type: object
                    properties:
                      value:
                        type: string
                      lang:
                        type: string
        proof:
          description: Digital proof that makes the credential tamper-evident.
          type: object
          properties:
            type:
              description: The cryptographic signature suite that was used to generate the signature
              type: string
            created:
              description: Time that this signature was created.
              type: string
              format: date-time
            proofPurpose:
              description: Pupose of this proof
              type: string
            verificationMethod:
              description: The identifier of the public key that can verify the signature
              type: string
            jws:
              description: The digital signature value
              type: string
    DidDocument:
      description: "We pulled this schema from: https://www.w3.org/TR/did-core/ and the DID document of this account in JSON format, including the public key in JWK format. "
      type: object
      required:
        - id
      properties:
        "@context":
          description: Sets the context, which establishes the special terms we will use like issuer and alumniOf
          type: string
        id:
          description: Identifier for the DID Document Subject
          type: string
        controller:
          description: Identifier for the controller DID.  This is an alternative to the id DID (subject)
          type: array
          items:
            type: string
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
        authentication:
          description: Authentication is a relationship between the DID subject and a set of verification methods.
          anyOf:
            - type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  type:
                    type: string
                  controller:
                    type: string
                  publicKey:
                    description: public key value
                    type: string
                  publicKeyType:
                    description: Type of public key. For instance, RSA, ed25519, secp256k1-koblitz, secp256r1, Curve25519
                    type: string
                  publicKeyEncoding:
                    description: Encoding used on the publickey value.  For instance, Base58(Bitcoin), base64url, or base16.  Apparently this is under discussion and these options may be limited in the future. https://www.w3.org/TR/did-core/
                    type: string
            - type: array
              items:
                type: string
        service:
          description: Service
          type: array
          items:
            type: object
            required:
              - id
              - type
              - serviceEndpoint
            properties:
              id:
                type: string
              type:
                type: string
              publicKey:
                type: string
              serviceEndpoint:
                type: string
        proof:
          description: Cryptographic proof of the integrity of the DID Document according to the subject(id) or controller
          properties:
            type:
              type: string
            created:
              description: Date and time of when this proof was created
              type: string
              format: date-time
            creator:
              description: DID of the creator
            signatureValue:
              description: value of the proof's signature
              type: string
    callerVerificationResponse:
      type: object
      required:
        - organization
        - vetter
        - tnAuthorizationResponse
      properties:
        organization:
          $ref: "#/components/schemas/AccountResponse"
        vetter:
          $ref: "#/components/schemas/AccountResponse"
        result:
          description: Result of the vetting process.  0 - Authorised, 1 - Not Authorised, 2 - Revoked
          type: integer
          format: int32
        vettedTS:
          description: Time that this Authorization became effective
          type: string
          format: date-time
        version:
          description: In the case that an Authorization is updated on the ledger, we will update the version. This will help to identify and order related Authorizations.
          type: integer
          format: int32
        tnAuthorizationResponse:
           $ref: "#/components/schemas/TNAuthorizationResponse"  
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string