openapi: 3.0.3
info:
  title: HAL API Service
  description: |
    # The HAL API services provides the following features
    - Gets organization account information
    - Gets payer and unit information per account

    ### How to Use This API
    To use this API, you must first login to https://hal.pearsoncloudmanagement.com or https://hal-dev.pearsoncloudmanagement.com, depending on which
    server environment you have selected on this API landing page.  Refer to https://pearsoneducationinc.sharepoint.com/sites/PearsonCloudManagement/SitePages/Helpful-Asset-Locator-(HAL)---Introduction.aspx
    for more details on how to login to HAL dev or prod, copy a javascript-generated accessToken into the auth token
    field on this page after login, and then try the API out, live.

    ### Release Notes
    v1.1.3
    - HAL internal fixes; no feature changes

    v1.1.2
    - Added accounts list feature (post-dated)

    v1.1.1
    - API landing site doc update

    v1.1.0
    - Upgraded HAL UI Frontend to use SAML AWS Cognito federation to EntraID (AzureAD).
      This provides backward compatibility supporting legacy SSO but with the added benefit
      of allow cognito API token generation and use support for backend AWS APIs.

    v1.0.5
    - Added support for OpenAPI to be imported and wired automatically in CDK IaC code.

    v1.0.4
    - More CDK and OpenAPI improvements.

    v1.0.3
    - CDK and OpenAPI improvements.

    v1.0.2
    - Cleanup and internal version release testing

    v1.0.1
    - Version testing

    v1.0.0
    - Initial API doc release
  version: 1.1.3
  contact:
    email: pcm-hal-support@pearson.com
  license:
    name: Pearson Proprietary
    url: 'https://pearsoneducationinc.sharepoint.com/sites/PearsonCloudManagement/SitePages/Helpful-Asset-Locator-(HAL)---Introduction.aspx'
servers:
  - url: 'https://api.pearsoncloudmanagement.com/hal'
    description: Production HAL API
  - url: 'https://api-dev.pearsoncloudmanagement.com/hal'
    description: Development HAL API
  - url: 'https://localhost:3000'
    description: Localhost HAL API
tags:
  - name: accounts
    description: Information about accounts and organizations
    externalDocs:
      description: Accounts Documentation
      url: 'https://pearsoneducationinc.sharepoint.com/sites/PearsonCloudManagement/SitePages/Helpful-Asset-Locator-(HAL)---Introduction.aspx'
  - name: payers
    description: Information about payers for accounts and organizations
    externalDocs:
      description: Payers Documentation
      url: 'https://pearsoneducationinc.sharepoint.com/sites/PearsonCloudManagement/SitePages/Helpful-Asset-Locator-(HAL)---Introduction.aspx'
paths:
  /payeraccountorgdetails:
    options:
      summary: CORS support for interactive API
      description: |
        Enable CORS by returning correct headers
      tags:
        - CORS
      responses:
        '200':
          description: Default response for CORS method
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content: {}
      security: []
      x-amazon-apigateway-integration:
        type: mock
        passthroughBehavior: never
        requestTemplates:
          application/json: |
            {
              "statusCode" : 200
            }
        responses:
          default:
            statusCode: '200'
            responseParameters:
              method.response.header.Access-Control-Allow-Headers: '''Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token,Api-Auth-Token'''
              method.response.header.Access-Control-Allow-Methods: '''*'''
              method.response.header.Access-Control-Allow-Origin: '''*'''
    get:
      tags:
        - payers
      summary: Find payers
      description: |
        Find payers for a given account
      operationId: findPayers
      responses:
        '200':
          description: successful operation
          headers:
            Content-Type:
              schema:
                type: string
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                description: Definition for the payer-org-units-and-policies json
                additionalProperties:
                  type: object
                  additionalProperties:
                    type: object
                    required:
                      - name
                      - AISERVICES_OPT_OUT_POLICY
                      - BACKUP_POLICY
                      - SERVICE_CONTROL_POLICY
                      - TAG_POLICY
                      - accounts
                    properties:
                      name:
                        type: string
                        example:
                          - Root
                          - Root/CloudEndureDR/Recovery
                      AISERVICES_OPT_OUT_POLICY:
                        type: array
                        items:
                          description: List of policies
                          type: object
                          minItems: 0
                          uniqueItems: true
                          required:
                            - Id
                            - Arn
                            - Name
                            - Type
                            - AwsManaged
                          properties:
                            Id:
                              type: string
                              example:
                                - p-FullAWSAccess
                                - p-v7joeyus
                            Arn:
                              type: string
                              example:
                                arn1:
                                  value: 'arn:aws:organizations::aws:policy/service_control_policy/p-FullAWSAccess'
                                arn2:
                                  value: 'arn:aws:organizations::150047381276:policy/o-njq6j1wsrz/service_control_policy/p-v7joeyus'
                            Name:
                              type: string
                              example:
                                - FullAWSAccess
                                - PreventAccessToDummy
                            Type:
                              type: string
                              enum:
                                - AISERVICES_OPT_OUT_POLICY
                                - BACKUP_POLICY
                                - SERVICE_CONTROL_POLICY
                                - TAG_POLICY
                            AwsManaged:
                              type: boolean
                      BACKUP_POLICY:
                        type: array
                        items:
                          description: List of policies
                          type: object
                          minItems: 0
                          uniqueItems: true
                          required:
                            - Id
                            - Arn
                            - Name
                            - Type
                            - AwsManaged
                          properties:
                            Id:
                              type: string
                              example:
                                - p-FullAWSAccess
                                - p-v7joeyus
                            Arn:
                              type: string
                              example:
                                arn1:
                                  value: 'arn:aws:organizations::aws:policy/service_control_policy/p-FullAWSAccess'
                                arn2:
                                  value: 'arn:aws:organizations::150047381276:policy/o-njq6j1wsrz/service_control_policy/p-v7joeyus'
                            Name:
                              type: string
                              example:
                                - FullAWSAccess
                                - PreventAccessToDummy
                            Type:
                              type: string
                              enum:
                                - AISERVICES_OPT_OUT_POLICY
                                - BACKUP_POLICY
                                - SERVICE_CONTROL_POLICY
                                - TAG_POLICY
                            AwsManaged:
                              type: boolean
                      SERVICE_CONTROL_POLICY:
                        type: array
                        items:
                          description: List of policies
                          type: object
                          minItems: 0
                          uniqueItems: true
                          required:
                            - Id
                            - Arn
                            - Name
                            - Type
                            - AwsManaged
                          properties:
                            Id:
                              type: string
                              example:
                                - p-FullAWSAccess
                                - p-v7joeyus
                            Arn:
                              type: string
                              example:
                                arn1:
                                  value: 'arn:aws:organizations::aws:policy/service_control_policy/p-FullAWSAccess'
                                arn2:
                                  value: 'arn:aws:organizations::150047381276:policy/o-njq6j1wsrz/service_control_policy/p-v7joeyus'
                            Name:
                              type: string
                              example:
                                - FullAWSAccess
                                - PreventAccessToDummy
                            Type:
                              type: string
                              enum:
                                - AISERVICES_OPT_OUT_POLICY
                                - BACKUP_POLICY
                                - SERVICE_CONTROL_POLICY
                                - TAG_POLICY
                            AwsManaged:
                              type: boolean
                      TAG_POLICY:
                        type: array
                        items:
                          description: List of policies
                          type: object
                          minItems: 0
                          uniqueItems: true
                          required:
                            - Id
                            - Arn
                            - Name
                            - Type
                            - AwsManaged
                          properties:
                            Id:
                              type: string
                              example:
                                - p-FullAWSAccess
                                - p-v7joeyus
                            Arn:
                              type: string
                              example:
                                arn1:
                                  value: 'arn:aws:organizations::aws:policy/service_control_policy/p-FullAWSAccess'
                                arn2:
                                  value: 'arn:aws:organizations::150047381276:policy/o-njq6j1wsrz/service_control_policy/p-v7joeyus'
                            Name:
                              type: string
                              example:
                                - FullAWSAccess
                                - PreventAccessToDummy
                            Type:
                              type: string
                              enum:
                                - AISERVICES_OPT_OUT_POLICY
                                - BACKUP_POLICY
                                - SERVICE_CONTROL_POLICY
                                - TAG_POLICY
                            AwsManaged:
                              type: boolean
                      accounts:
                        type: array
                        items:
                          description: List of accounts belonging to the OU
                          type: string
                          minItems: 0
                          uniqueItems: true
                          pattern: '[0-9]{12}'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '500':
          description: Server error.  Try again.
      security:
        - HalUserPool:
            - hal/account-org-data.readonly
      x-amazon-apigateway-integration:
        passthroughBehavior: when_no_match
        uri:
          'Fn::Sub': 'arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${HalApiEndpoint.Arn}/invocations'
        httpMethod: POST
        type: aws_proxy
        contentHandling: CONVERT_TO_TEXT
        responses:
          default:
            statusCode: 200
            responseParameters:
              method.response.header.Access-Control-Allow-Headers: '''Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token,Api-Auth-Token'''
              method.response.header.Access-Control-Allow-Methods: '''*'''
              method.response.header.Access-Control-Allow-Origin: '''*'''
  /accountsandorgdata:
    options:
      summary: CORS support for interactive API
      description: |
        Enable CORS by returning correct headers
      tags:
        - CORS
      responses:
        '200':
          description: Default response for CORS method
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content: {}
      security: []
      x-amazon-apigateway-integration:
        type: mock
        passthroughBehavior: never
        requestTemplates:
          application/json: |
            {
              "statusCode" : 200
            }
        responses:
          default:
            statusCode: '200'
            responseParameters:
              method.response.header.Access-Control-Allow-Headers: '''Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token,Api-Auth-Token'''
              method.response.header.Access-Control-Allow-Methods: '''*'''
              method.response.header.Access-Control-Allow-Origin: '''*'''
    get:
      tags:
        - accounts
      summary: Find accounts
      description: |
        Find accounts and org info
      operationId: findAccounts
      responses:
        '200':
          description: successful operation
          headers:
            Content-Type:
              schema:
                type: string
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                description: Definition for the accounts-to-org-units json
                additionalProperties:
                  type: object
                  required:
                    - Id
                    - Arn
                    - Email
                    - Name
                    - Status
                    - JoinedMethod
                    - JoinedTimestamp
                    - unit_path
                    - unit_id
                    - payer_account_id
                  properties:
                    Id:
                      type: string
                      pattern: '[0-9]{12}'
                      example:
                        Id1:
                          value: '837810110612'
                        Id2:
                          value: '138512462893'
                    Arn:
                      type: string
                      pattern: 'arn:aws:organizations::[0-9]{12}:account/o-[a-z0-9]*/[0-9]{12}'
                      example:
                        arn1:
                          value: 'arn:aws:organizations::150047381276:account/o-njq6j1wsrz/689157341164'
                        arn2:
                          value: 'arn:aws:organizations::150047381276:account/o-njq6j1wsrz/712176489324'
                    Email:
                      type: string
                      format: email
                      example:
                        email1:
                          value: aes-prd@amazon.pearson.com
                        email2:
                          value: 3plcg-nonprd@amazon.pearson.com
                    Name:
                      type: string
                      example:
                        name1:
                          value: aes-prd
                        name2:
                          value: 3plcg-nonprd
                    Status:
                      type: string
                      enum:
                        - ACTIVE
                        - SUSPENDED
                        - PENDING_CLOSURE
                    JoinedMethod:
                      type: string
                      enum:
                        - INVITED
                        - CREATED
                    JoinedTimestamp:
                      type: string
                      format: date-time
                    unit_path:
                      type: string
                      example:
                        oupath1:
                          value: Root/CIOMasterOU/Production
                        oupath2:
                          value: Root/CIOMasterOU/Non-Production
                    unit_id:
                      type: string
                      example:
                        ou1:
                          value: ou-pjk3-neqbpt9x
                        out2:
                          value: ou-pjk3-azmbm7vc
                    payer_account_id:
                      type: string
                      pattern: '[0-9]{12}'
                      example:
                        id1:
                          value: '150047381276'
                        id2:
                          value: '958342668309'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '500':
          description: Server error.  Try again.
      security:
        - HalUserPool:
            - hal/account-org-data.readonly
      x-amazon-apigateway-integration:
        passthroughBehavior: when_no_match
        httpMethod: POST
        uri:
          'Fn::Sub': 'arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${HalApiEndpoint.Arn}/invocations'
        type: aws_proxy
        contentHandling: CONVERT_TO_TEXT
        responses:
          default:
            statusCode: 200
            responseParameters:
              method.response.header.Access-Control-Allow-Headers: '''Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token,Api-Auth-Token'''
              method.response.header.Access-Control-Allow-Methods: '''*'''
              method.response.header.Access-Control-Allow-Origin: '''*'''
  /cloudaccountslist:
    options:
      summary: CORS support for interactive API
      description: |
        Enable CORS by returning correct headers
      tags:
        - CORS
      responses:
        '200':
          description: Default response for CORS method
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content: {}
      security: []
      x-amazon-apigateway-integration:
        type: mock
        passthroughBehavior: never
        requestTemplates:
          application/json: |
            {
              "statusCode" : 200
            }
        responses:
          default:
            statusCode: '200'
            responseParameters:
              method.response.header.Access-Control-Allow-Headers: '''Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token,Api-Auth-Token'''
              method.response.header.Access-Control-Allow-Methods: '''*'''
              method.response.header.Access-Control-Allow-Origin: '''*'''
    get:
      summary: Get Accounts List
      description: |
        List of Cloud Accounts with basic information
      operationId: cloudaccountslist
      responses:
        '200':
          description: successful operation
          headers:
            Content-Type:
              schema:
                type: string
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                description: Definition for the cloudaccountslist json
                additionalProperties:
                  type: object
                  properties:
                    results:
                      type: array
                      items:
                        type: object
                        properties:
                          cloud_platform:
                            type: string
                            example:
                              cloud_platform1:
                                value: AWS
                              cloud_platform2:
                                value: AZURE
                          account_id:
                            type: string
                            example:
                              account_id1:
                                value: 000177003864
                              account_id2:
                                value: 000690637771
                          account_closed:
                            type: string
                            example:
                              'yes':
                                value: 'Y'
                              'no':
                                value: 'N'
                          account_type:
                            type: string
                            example:
                              account_type1:
                                value: Production
                              account_type2:
                                value: Non-Production
                          cloud_account_name:
                            type: string
                            example:
                              cloud_account_name1:
                                value: gpt-seer-prod
                              cloud_account_name2:
                                value: gptx-xl-2.0-nonprd
                          account_alias:
                            type: string
                            example:
                              account_alias1:
                                value: gpt-seer-prod
                              account_alias2:
                                value: gptx-xl-2.0-nonprd
                          cloud_account_root_email:
                            type: string
                            format: email
                          funding_application_tappid:
                            type: string
                            example:
                              tappid1:
                                value: SVC00943
                              tappid2:
                                value: SVC02568
                          provisioner:
                            type: string
                            example:
                              provisioner1:
                                value: PCM
                          create_date:
                            type: string
                            format: date
                          payer_account:
                            type: string
                          account_lob:
                            type: string
                          account_tower:
                            type: string
                          budget_account_string:
                            type: string
                          account_owner:
                            type: string
                          account_technical:
                            type: string
                          row_num:
                            type: string
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '500':
          description: Server error.  Try again.
      security:
        - HalUserPool:
            - hal/account-org-data.readonly
      x-amazon-apigateway-integration:
        passthroughBehavior: when_no_match
        httpMethod: POST
        uri:
          'Fn::Sub': 'arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${HalApiEndpoint.Arn}/invocations'
        type: aws_proxy
        contentHandling: CONVERT_TO_TEXT
        responses:
          default:
            statusCode: 200
            responseParameters:
              method.response.header.Access-Control-Allow-Headers: '''Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token,Api-Auth-Token'''
              method.response.header.Access-Control-Allow-Methods: '''*'''
              method.response.header.Access-Control-Allow-Origin: '''*'''
  /healthcheck:
    get:
      tags:
        - healthstatus
      summary: Find health and status
      description: |
        Find health and status
      operationId: findHealthStatus
      responses:
        '200':
          description: successful operation
          headers:
            Content-Type:
              schema:
                type: string
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '500':
          description: Server error.  Try again.
      security: []
      x-amazon-apigateway-integration:
        passthroughBehavior: when_no_match
        httpMethod: POST
        uri:
          'Fn::Sub': 'arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${HalApiEndpoint.Arn}/invocations'
        type: aws_proxy
        contentHandling: CONVERT_TO_TEXT
        responses:
          default:
            statusCode: 200
            responseParameters:
              method.response.header.Access-Control-Allow-Headers: '''Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token,Api-Auth-Token'''
              method.response.header.Access-Control-Allow-Methods: '''*'''
              method.response.header.Access-Control-Allow-Origin: '''*'''
  /:
    get:
      summary: API landing page
      operationId: APILandingPage
      responses:
        '200':
          description: Default 200 response for CORS method
          headers:
            Content-Type:
              schema:
                type: string
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content: {}
        '404':
          description: API landing page not found
          headers:
            Content-Type:
              schema:
                type: string
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content: {}
      security: []
      x-amazon-apigateway-integration:
        responses:
          default:
            statusCode: '200'
            responseParameters:
              method.response.header.Content-Type: '''text/html'''
              method.response.header.Access-Control-Allow-Headers: '''Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token,Api-Auth-Token'''
              method.response.header.Access-Control-Allow-Methods: '''*'''
              method.response.header.Access-Control-Allow-Origin: '''*'''
            responseTemplates:
              text/html: |
                <!DOCTYPE html> <html lang="en">
                  <head>
                    <meta charset="utf-8"> <!-- Important: rapi-doc uses utf8 charecters -->
                    <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
                  </head>
                  <body>
                    <!-- Swagger build propagates info.version. Change the version in openapi.yaml, not here. v0.0.0 is a placeholder. -->
                    <rapi-doc spec-url = "https://downloads.pearsoncloudmanagement.com/hal/$context.stage/api/openapi_bundled_v1.1.3.yaml"> </rapi-doc>
                  </body>
                </html>
        requestTemplates:
          application/json: '{"statusCode": 200}'
        passthroughBehavior: when_no_match
        type: mock
externalDocs:
  description: Find out more about HAL and its Capabilities
  url: 'https://pearsoneducationinc.sharepoint.com/sites/PearsonCloudManagement/SitePages/Helpful-Asset-Locator-(HAL)---Introduction.aspx?web=1'
components:
  securitySchemes:
    HalUserPool:
      type: apiKey
      name: Authorization
      in: header
      x-amazon-apigateway-authtype: cognito_user_pools
      x-amazon-apigateway-authorizer:
        type: cognito_user_pools
        providerARNs:
          - 'Fn::Sub': '${HalUserPool.Arn}'
