openapi: 3.0.0
info:
  title: App Credentials Webhook
  description: |
    This specification defines the API endpoints for managing app credentials via webhook integration with Sensedia's Developer Portal.
  version: 1.0.0
servers:
  - url: https://{{baseurl}}
paths:
  /v1/createCredentials:
    post:
      tags:
        - Credentials Management
      summary: Create Credentials
      description: Creates credentials for a specific app. It can generate API Keys or Client Credentials, according to the underlying implementation.
      security:
        - basicAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCredentialsRequest"
            example:
              appName: my new aws app
              appSlug: 590d83b5c05f
              developer: email@mycompany.com
              apis:
                - id: 5aba4csvd4
                  usagePlans:
                    - id: 1el57v
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/json
        - name: Accept
          in: header
          schema:
            type: string
          example: application/json
      responses:
        "200":
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateCredentialsResponse"
              examples:
                example-0:
                  summary: Create credentials with client_credentials
                  value:
                    credentialType: CLIENT_CREDENTIALS
                    clientId: 36no66vp1ul665nhmse38gcg7v
                    clientSecret: sa4uekd5gl6007ee86g8crnhjnsvo7l91i647n6ijgs59i1nink
                    customCredentials:
                      key1: value1
                      key2: value2
                example-1:
                  summary: Create credentials with api_key
                  value:
                    credentialType: API_KEY
                    apiKeyId: 1gi2ha2ejk
                    apiKey: scvyUdlO3a3xhNsy3hlUD3qbwBEL3ylO85PBrt5l
                    customCredentials:
                      key1: value1
                      key2: value2
        "500":
          description: Internal Server Error
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorDTO"
  /v1/updateCredentials:
    post:
      tags:
        - Credentials Management
      summary: Update Credentials
      description: Update credentials for a specific app.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateCredentialsRequest"
            example:
              updatedAt: 2024-03-01T18:58:47.878561013Z[GMT]
              appSlug: 590d83b5c05f
              appName: string
              developer: string
              credentialType: API_KEY
              clientId: string
              apiKeyId: basinxe9k3
              customCredentials:
                key1: value1
                key2: value2
              apis:
                - usagePlans:
                    - id: yquo6a
                      action: ADDED
                  action: NONE
                  id: 35qs940bd2
      security:
        - basicAuth: []
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/json
        - name: Accept
          in: header
          schema:
            type: string
          example: application/json
      responses:
        "204":
          description: No Content
        "500":
          description: Internal Server Error
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorDTO"
  /v1/revokeCredentials:
    post:
      tags:
        - Credentials Management
      summary: Revoke Credentials
      description: Revokes credentials for a specific app.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RevokeCredentialsRequest"
            example:
              appSlug: 590d83b5c05f
              appName: string
              developer: string
              credentialType: API_KEY
              clientId: string
              clientSecret: string
              apiKeyId: basinxe9k3
              apiKey: string
              customCredentials:
                key1: value1
                key2: value2
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/json
        - name: Accept
          in: header
          schema:
            type: string
          example: application/json
      responses:
        "204":
          description: No Content
        "500":
          description: Internal Server Error
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorDTO"
  /v1/health:
    get:
      tags:
        - System
      summary: Check Health
      description: Checks the health of the webhook.
      security:
        - basicAuth: []
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorDTO"
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  schemas:
    CreateCredentialsRequest:
      type: object
      properties:
        appName:
          description: App name defined by the developer in Developer Portal
          type: string
          maxLength: 255
        appSlug:
          description: App unique identification
          type: string
          maxLength: 12
        developer:
          description: Developer's email who created the app in Developer Portal
          type: string
          maxLength: 255
        apis:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: AWS API Gateway's API Id
              usagePlans:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: AWS API Gateway's Usage Plan Id
    UpdateCredentialsRequest:
      type: object
      properties:
        updatedAt:
          description: Date when app was updated by the developer
          type: string
          format: date-time
        appName:
          description: App name defined by the developer in Developer Portal
          type: string
          maxLength: 255
        appSlug:
          description: App unique identification
          type: string
          maxLength: 12
        developer:
          description: Developer's email who created the app in Developer Portal
          type: string
          maxLength: 255
        credentialType:
          description: Type of credential
          type: string
          enum:
            - CLIENT_CREDENTIALS
            - API_KEY
        clientId:
          description: Client Id from AWS Cognito's app client
          type: string
          maxLength: 26
        apiKeyId:
          description: API Key Id from AWS API Gateway
          type: string
          maxLength: 10
        apiKey:
          description: API Key value from AWS API Gateway
          type: string
          maxLength: 40
        customCredentials:
          description: Custom credentials that were provided in the creation of the app
          type: object
        apis:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: AWS API Gateway's API Id
              action:
                description: Action performed in this API in the last update
                type: string
                enum:
                  - ADDED
                  - REMOVED
                  - NONE
              usagePlans:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: AWS API Gateway's Usage Plan Id
                    action:
                      description: Action performed in this Usage Plan in the last update
                      type: string
                      enum:
                        - ADDED
                        - REMOVED
                        - NONE
    RevokeCredentialsRequest:
      type: object
      properties:
        clientId:
          description: Client Id from AWS Cognito's app client
          type: string
          maxLength: 26
        apiKeyId:
          description: API Key from AWS API Gateway stored in Developer Portal's database
          type: string
          maxLength: 10
        appSlug:
          description: App unique identification
          type: string
          maxLength: 12
        customCredentials:
          description: Custom credentials that were provided in the creation of the app
          type: object
    CreateCredentialsResponse:
      type: object
      properties:
        credentialType:
          description: Possible credentials types that can be created. Other fields should be filled according to this type
          type: string
          enum:
            - CLIENT_CREDENTIALS
            - API_KEY
        clientId:
          description: Created Client Id from AWS Cognito's app client list. Required when 'credentialType' is 'CLIENT_CREDENTIALS'
          type: string
          maxLength: 26
        clientSecret:
          description: Created Client Secret from AWS Cognito's app client list. Required when 'credentialType' is 'CLIENT_CREDENTIALS'
          type: string
          maxLength: 51
        apiKeyId:
          description: Created API Key Id from AWS API Gateway. Required when 'credentialType' is 'API_KEY'
          type: string
          maxLength: 10
        apiKey:
          description: Created API Key value from AWS API Gateway. Required when 'credentialType' is 'API_KEY'
          type: string
          maxLength: 40
        customCredentials:
          description: Custom credentials that can be passed to the developer. It can be used to store any kind of credential in the key:value format
          type: object
    ErrorDTO:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        status:
          type: integer
          format: int32
        error:
          type: string
        messages:
          type: array
          items:
            type: string
          uniqueItems: true
        path:
          type: string