@epilot/sdk 2.7.0 → 2.8.0-rc.0

package/definitions/customer-portal.json

@@ -1867,6 +1867,13 @@
                               "example": "CAA_ERROR"
                             }
                           }
+                        },
+                        "identity_providers": {
+                          "type": "array",
+                          "description": "SSO identity providers configured for the portal. Includes raw\n`oidc_config.client_secret` values so the admin UI can round-trip\nthem. Customers are encouraged to reference secrets via env\ntemplates (`{{ env.VAR }}`) rather than embed raw values.\n",
+                          "items": {
+                            "$ref": "#/components/schemas/ProviderConfig"
+                          }
                         }
                       }
                     }
@@ -1994,6 +2001,13 @@
                               "example": "CAA_ERROR"
                             }
                           }
+                        },
+                        "identity_providers": {
+                          "type": "array",
+                          "description": "SSO identity providers configured for the portal. Includes raw\n`oidc_config.client_secret` values so the admin UI can round-trip\nthem. Customers are encouraged to reference secrets via env\ntemplates (`{{ env.VAR }}`) rather than embed raw values.\n",
+                          "items": {
+                            "$ref": "#/components/schemas/ProviderConfig"
+                          }
                         }
                       }
                     }
@@ -3561,6 +3575,84 @@
                     "contactId": {
                       "$ref": "#/components/schemas/EntityId",
                       "description": "ID of the contact if exists"
+                    },
+                    "accountId": {
+                      "$ref": "#/components/schemas/EntityId",
+                      "description": "ID of the resolved account when the portal is configured for account-based registration"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/InvalidRequest"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v3/portal/public/account/exists": {
+      "post": {
+        "operationId": "checkAccountExists",
+        "summary": "checkAccountExists",
+        "description": "True if account with given identifiers exists.\nSupports two identification methods:\n1. Using portal_id\n2. Using domain\n",
+        "security": [],
+        "tags": [
+          "Public"
+        ],
+        "parameters": [
+          {
+            "in": "query",
+            "name": "portal_id",
+            "required": false,
+            "schema": {
+              "$ref": "#/components/schemas/PortalId"
+            },
+            "description": "PortalId of the portal (required if domain is not provided)"
+          },
+          {
+            "in": "query",
+            "name": "domain",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Portal domain for identification (alternative to portal_id)"
+          }
+        ],
+        "requestBody": {
+          "description": "Request payload",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AccountExistsRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Return result true|false if the account with given identifiers exists.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "exists": {
+                      "type": "boolean",
+                      "description": "Whether the account exists with the given identifier values",
+                      "example": true
+                    },
+                    "accountId": {
+                      "$ref": "#/components/schemas/EntityId",
+                      "description": "ID of the account if exists"
                     }
                   }
                 }
@@ -7527,6 +7619,90 @@
         }
       }
     },
+    "/v2/portal/public/sso/providers/{provider_slug}": {
+      "get": {
+        "operationId": "getSSOProvider",
+        "summary": "getSSOProvider",
+        "description": "Returns the public configuration of a single SSO identity provider with env var\nplaceholders (incl. secrets) already resolved against the organization's environment.\n\nUse this endpoint at SSO initiation time (i.e. when the end user clicks \"Sign in with X\")\nto obtain the resolved OIDC settings needed to construct the authorization URL.\nThe web `client_secret` is intentionally never returned — it is used server-side by\nthe SSO callback to exchange the authorization code for tokens.\n\nSupports three identification methods:\n1. `org_id` + `origin`\n2. `org_id` + `portal_id`\n3. `domain`\n",
+        "security": [],
+        "tags": [
+          "Public"
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "provider_slug",
+            "required": true,
+            "description": "Provider slug (organization-unique)",
+            "schema": {
+              "$ref": "#/components/schemas/ProviderSlug"
+            }
+          },
+          {
+            "in": "query",
+            "name": "org_id",
+            "required": false,
+            "description": "epilot organization id (required with `origin` or `portal_id`)",
+            "schema": {
+              "type": "string",
+              "example": 123
+            }
+          },
+          {
+            "in": "query",
+            "name": "origin",
+            "required": false,
+            "description": "Origin of the Portal",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "END_CUSTOMER_PORTAL",
+                "INSTALLER_PORTAL"
+              ]
+            }
+          },
+          {
+            "in": "query",
+            "name": "portal_id",
+            "required": false,
+            "description": "ID of the Portal",
+            "schema": {
+              "$ref": "#/components/schemas/PortalId"
+            }
+          },
+          {
+            "in": "query",
+            "name": "domain",
+            "required": false,
+            "description": "Portal domain for identification (alternative to org_id + origin/portal_id)",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Resolved public SSO provider configuration. The handler strips `oidc_config.client_secret` from the response (kept server-side for the token exchange); the schema includes it for shape compatibility with the portal-config response.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProviderPublicConfig"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/InvalidRequest"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
     "/v2/portal/public/sso/login": {
       "post": {
         "operationId": "ssoLogin",
@@ -9718,6 +9894,149 @@
           }
         }
       }
+    },
+    "/v3/portal/verify-dns": {
+      "post": {
+        "operationId": "verifyDns",
+        "summary": "verifyDns",
+        "description": "Manually triggers DNS verification for a portal's domain setup. Runs the same verification logic as the scheduled processAllPendingNetworks lambda.",
+        "tags": [
+          "ECP Admin"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "query",
+            "name": "portal_id",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/PortalId"
+            },
+            "description": "PortalId of the portal"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "DNS verification result",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "domain_status": {
+                      "type": "string",
+                      "description": "The status of the custom domain verification",
+                      "enum": [
+                        "PENDING",
+                        "SUCCEED"
+                      ]
+                    },
+                    "message": {
+                      "type": "string",
+                      "description": "A message describing the result"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/portal/proxy/execute": {
+      "post": {
+        "operationId": "portalProxyExecute",
+        "summary": "portalProxyExecute",
+        "description": "Execute an Integration Hub managed-call use case on behalf of a portal user.\nBridges PortalAuth to the Integration API by generating an internal token.\n",
+        "security": [
+          {
+            "PortalAuth": []
+          }
+        ],
+        "tags": [
+          "ECP"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "integration_id",
+                  "use_case_slug"
+                ],
+                "properties": {
+                  "integration_id": {
+                    "type": "string",
+                    "format": "uuid",
+                    "description": "Integration ID containing the managed-call use case"
+                  },
+                  "use_case_slug": {
+                    "type": "string",
+                    "description": "Use case slug (acts as the RPC method name)"
+                  },
+                  "payload": {
+                    "type": "object",
+                    "description": "Input data for the managed-call operation",
+                    "additionalProperties": true
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Managed-call execution result envelope.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "success"
+                  ],
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "data": {
+                      "type": "object",
+                      "additionalProperties": true,
+                      "description": "Managed-call response payload. Shape is defined by the use\ncase's JSONata response_mapping; if no mapping is\nconfigured the raw external API response is returned.\n"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/InvalidRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
     }
   },
   "components": {
@@ -10403,6 +10722,13 @@
                 "description": "Default admin users for pending user notification to notify"
               }
             }
+          },
+          "identity_providers": {
+            "type": "array",
+            "description": "SSO identity providers for the portal. When sent on a portal save (PUT/POST),\nthe list is fully synced — incoming providers are upserted and any existing\nproviders not in the list are deleted. Omit the field to leave SSO\nconfiguration unchanged; send an empty array to remove all providers.\n\nEach provider is persisted verbatim — `oidc_config.client_secret` is stored\nas sent. Customers are encouraged to reference an org env secret via\n`{{ env.VAR }}` rather than embed raw values.\n",
+            "items": {
+              "$ref": "#/components/schemas/ProviderConfig"
+            }
           }
         }
       },
@@ -10430,6 +10756,14 @@
             "type": "boolean",
             "description": "Mark true if the domain is an Epilot domain"
           },
+          "epilot_domain": {
+            "type": "string",
+            "description": "The URL on which the portal is accessible",
+            "example": "example-portal-12345.ecp.epilot.cloud"
+          },
+          "domain_settings": {
+            "$ref": "#/components/schemas/DomainSettings"
+          },
           "design_id": {
             "$ref": "#/components/schemas/EntityId",
             "description": "ID of the design used to build the portal"
@@ -10456,6 +10790,24 @@
               "BLOCK_IF_PORTAL_USER_EXISTS"
             ]
           },
+          "self_registration_account_setting": {
+            "type": "string",
+            "description": "Controls behavior of self-registration when account is used as the registration entity",
+            "enum": [
+              "ALLOW_WITH_CONTACT_CREATION",
+              "DENY",
+              "ALWAYS_CREATE_CONTACT",
+              "DISALLOW_COMPLETELY"
+            ]
+          },
+          "self_registration_entity": {
+            "type": "string",
+            "description": "Entity type used as the primary identifier for self-registration",
+            "enum": [
+              "contact",
+              "account"
+            ]
+          },
           "user_account_self_management": {
             "type": "boolean",
             "description": "Enable or disable user account self management",
@@ -10880,6 +11232,13 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/Page"
             }
+          },
+          "global_blocks": {
+            "type": "object",
+            "description": "Portal-level blocks shared across all pages (e.g. footer). Keyed by block id.",
+            "additionalProperties": {
+              "$ref": "#/components/schemas/Block"
+            }
           }
         }
       },
@@ -10986,6 +11345,24 @@
           }
         }
       },
+      "DomainSettings": {
+        "type": "object",
+        "description": "Domain settings for the portal",
+        "properties": {
+          "is_custom_domain_enabled": {
+            "type": "boolean",
+            "description": "Whether the custom domain is enabled"
+          },
+          "is_epilot_domain_enabled": {
+            "type": "boolean",
+            "description": "Whether the Epilot domain is enabled"
+          },
+          "is_redirection_enabled": {
+            "type": "boolean",
+            "description": "Whether the redirection is enabled"
+          }
+        }
+      },
       "WidgetBase": {
         "type": "object",
         "required": [
@@ -11342,6 +11719,38 @@
           }
         }
       },
+      "AccountExistsRequest": {
+        "type": "object",
+        "required": [
+          "registration_identifiers",
+          "org_id"
+        ],
+        "properties": {
+          "org_id": {
+            "type": "string",
+            "example": 728,
+            "description": "ID of the organization"
+          },
+          "registration_identifiers": {
+            "type": "object",
+            "description": "Identifier-value pairs per schema to identify an account during portal user registration",
+            "additionalProperties": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              }
+            },
+            "example": {
+              "account": {
+                "customer_number": "ACC-123456"
+              },
+              "contract": {
+                "contract_number": "123456"
+              }
+            }
+          }
+        }
+      },
       "UserRequest": {
         "type": "object",
         "properties": {
@@ -14471,6 +14880,11 @@
                 "type": "string",
                 "description": "Lower allowed limit of the meter reading",
                 "example": "{{CallResponse.data.lower_limit}}"
+              },
+              "errorMessagePath": {
+                "type": "string",
+                "description": "Optional path to a human-readable error message in the third-party response body, used when the call fails (non-2xx status).\nIf specified and the path resolves to a string, that message is forwarded to the end user instead of a generic error.\n",
+                "example": "error.message"
               }
             }
           },
@@ -14550,6 +14964,11 @@
               "dataPath": {
                 "type": "string",
                 "description": "Optional path to the data (array) in the response. If omitted, the data is assumed to be on the top level."
+              },
+              "errorMessagePath": {
+                "type": "string",
+                "description": "Optional path to a human-readable error message in the third-party response body, used when the call fails (non-2xx status).\nIf specified and the path resolves to a string, that message is forwarded to the end user instead of a generic error.\n",
+                "example": "error.message"
               }
             }
           },
@@ -14628,6 +15047,11 @@
               "dataPath": {
                 "type": "string",
                 "description": "Optional path to the data (array) in the response. If omitted, the data is assumed to be on the top level."
+              },
+              "errorMessagePath": {
+                "type": "string",
+                "description": "Optional path to a human-readable error message in the third-party response body, used when the call fails (non-2xx status).\nIf specified and the path resolves to a string, that message is forwarded to the end user instead of a generic error.\n",
+                "example": "error.message"
               }
             }
           },
@@ -14707,6 +15131,16 @@
               "url"
             ]
           },
+          "resolved": {
+            "type": "object",
+            "properties": {
+              "errorMessagePath": {
+                "type": "string",
+                "description": "Optional path to a human-readable error message in the third-party response body, used when the call fails (non-2xx status).\nIf specified and the path resolves to a string, that message is forwarded to the end user instead of a generic error.\n",
+                "example": "error.message"
+              }
+            }
+          },
           "use_static_ips": {
             "type": "boolean",
             "deprecated": true,
@@ -14782,6 +15216,11 @@
               "dataPath": {
                 "type": "string",
                 "description": "Optional path to the metadata object in the response. If omitted, the metadata is assumed to be on the top level."
+              },
+              "errorMessagePath": {
+                "type": "string",
+                "description": "Optional path to a human-readable error message in the third-party response body, used when the call fails (non-2xx status).\nIf specified and the path resolves to a string, that message is forwarded to the end user instead of a generic error.\n",
+                "example": "error.message"
               }
             }
           },
@@ -14860,6 +15299,11 @@
               "dataPath": {
                 "type": "string",
                 "description": "Optional path to the data (array) in the response. If omitted, the data is assumed to be on the top level."
+              },
+              "errorMessagePath": {
+                "type": "string",
+                "description": "Optional path to a human-readable error message in the third-party response body, used when the call fails (non-2xx status).\nIf specified and the path resolves to a string, that message is forwarded to the end user instead of a generic error.\n",
+                "example": "error.message"
               }
             }
           },
@@ -15181,6 +15625,7 @@
       },
       "ProviderConfig": {
         "type": "object",
+        "description": "SSO identity provider configuration.\n\nEnv var interpolation: only string fields under `oidc_config` and\n`mobile_oidc_config` (incl. their nested `metadata`) are passed through\nLiquid templating, so they may contain `{{ env.VAR }}` placeholders that\nget resolved at runtime against the organization's environment.\n\nThe following fields are used as literal values and MUST NOT contain\ntemplate syntax: `slug`, `display_name`, `provider_type`, all keys and\nvalues under `attribute_mappings` (used as JSONPath-like accessors into\ntoken claims), and all keys and values under `entity_matching`.\n",
         "properties": {
           "slug": {
             "$ref": "#/components/schemas/ProviderSlug"
@@ -15372,6 +15817,7 @@
       },
       "OIDCProviderConfig": {
         "type": "object",
+        "description": "OIDC provider configuration. Values are resolved at SSO invocation time\n(login / callback), so the fields below may reference org env vars via\nmustache-like templates, e.g. `{{ env.MY_PROVIDER_CLIENT_SECRET }}`.\n\nFields used to render the SSO buttons up-front (`ProviderConfig.slug`,\n`ProviderConfig.display_name`) are NOT interpolated and must be literal.\n",
         "properties": {
           "type": {
             "type": "string",
@@ -15383,20 +15829,22 @@
           },
           "oidc_issuer": {
             "type": "string",
-            "description": "Issuing Authority URL",
+            "description": "Issuing Authority URL. Supports env var interpolation, e.g. `{{ env.MY_ISSUER }}`.",
             "example": "https://login.microsoftonline.com/33d4f3e5-3df2-421e-b92e-a63cfa680a88/v2.0"
           },
           "redirect_uri": {
             "type": "string",
-            "description": "Redirect URI for the OIDC flow",
+            "description": "Redirect URI for the OIDC flow. Supports env var interpolation.",
             "example": "https://customer-portal.com/login"
           },
           "client_id": {
             "type": "string",
+            "description": "Supports env var interpolation, e.g. `{{ env.MY_CLIENT_ID }}`.",
             "example": "ab81daf8-8b1f-42d6-94ca-c51621054c75"
           },
           "client_secret": {
             "type": "string",
+            "description": "Client Secret. Supports env var interpolation (incl. secrets), e.g.\n`{{ env.MY_CLIENT_SECRET }}`. Prefer storing the actual secret as an org\nenv var and referencing it here.\n",
             "example": "7BIUnn~6shh.7fNtXb..3k1Mp3s6k6WK3B"
           },
           "has_client_secret": {
@@ -15429,15 +15877,16 @@
       },
       "MoblieOIDCConfig": {
         "type": "object",
+        "description": "Mobile OIDC configuration. Values are resolved at SSO invocation time, so the\nfields below may reference org env vars via mustache-like templates, e.g.\n`{{ env.MOBILE_CLIENT_SECRET }}`.\n",
         "properties": {
           "client_id": {
             "type": "string",
-            "description": "Client ID for the mobile app",
+            "description": "Client ID for the mobile app. Supports env var interpolation.",
             "example": 123456
           },
           "client_secret": {
             "type": "string",
-            "description": "Client Secret for the mobile app",
+            "description": "Client Secret for the mobile app. Supports env var interpolation (incl. secrets),\ne.g. `{{ env.MOBILE_CLIENT_SECRET }}`.\n",
             "example": 123456
           }
         }
@@ -15445,6 +15894,18 @@
       "OIDCProviderMetadata": {
         "type": "object",
         "properties": {
+          "response_modes_supported": {
+            "type": "array",
+            "description": "Response modes the provider accepts (e.g. `form_post` for Apple)",
+            "items": {
+              "type": "string",
+              "enum": [
+                "form_post",
+                "fragment",
+                "query"
+              ]
+            }
+          },
           "authorization_endpoint": {
             "type": "string",
             "description": "URL of the authorization endpoint",
@@ -15482,12 +15943,12 @@
           },
           "test_auth_username": {
             "type": "string",
-            "description": "The username for the test auth, only used for testing on auth code flow",
+            "description": "The username for the test auth, only used for testing on auth code flow.\nSupports env var interpolation, e.g. `{{ env.MY_TEST_AUTH_USERNAME }}`.\n",
             "example": "test@epilot.io"
           },
           "test_auth_password": {
             "type": "string",
-            "description": "The password for the test auth, only used for testing on auth code flow"
+            "description": "The password for the test auth, only used for testing on auth code flow.\nSupports env var interpolation (incl. secrets), e.g. `{{ env.MY_TEST_AUTH_PASSWORD }}`.\n"
           }
         }
       },
@@ -15924,6 +16385,14 @@
             "type": "boolean",
             "description": "Mark true if the domain is an Epilot domain"
           },
+          "epilot_domain": {
+            "type": "string",
+            "description": "The Epilot domain on which the portal is accessible",
+            "example": "example-portal-1.ecp.epilot.io"
+          },
+          "domain_settings": {
+            "$ref": "#/components/schemas/DomainSettings"
+          },
           "design_id": {
             "$ref": "#/components/schemas/EntityId",
             "description": "ID of the design used to build the portal"
@@ -15950,6 +16419,24 @@
               "BLOCK_IF_PORTAL_USER_EXISTS"
             ]
           },
+          "self_registration_account_setting": {
+            "type": "string",
+            "description": "Controls behavior of self-registration when account is used as the registration entity",
+            "enum": [
+              "ALLOW_WITH_CONTACT_CREATION",
+              "DENY",
+              "ALWAYS_CREATE_CONTACT",
+              "DISALLOW_COMPLETELY"
+            ]
+          },
+          "self_registration_entity": {
+            "type": "string",
+            "description": "Entity type used as the primary identifier for self-registration",
+            "enum": [
+              "contact",
+              "account"
+            ]
+          },
           "user_account_self_management": {
             "type": "boolean",
             "description": "Enable or disable user account self management",
@@ -16368,6 +16855,13 @@
           },
           "origin": {
             "$ref": "#/components/schemas/Origin"
+          },
+          "global_blocks": {
+            "type": "object",
+            "description": "Portal-level blocks shared across all pages (e.g. footer). Keyed by block id.",
+            "additionalProperties": {
+              "$ref": "#/components/schemas/Block"
+            }
           }
         }
       },
@@ -16480,6 +16974,11 @@
           "is_canary": {
             "type": "boolean",
             "description": "Whether the org is in canary mode"
+          },
+          "redirect_to": {
+            "type": "string",
+            "description": "The URL to redirect to",
+            "example": "https://example.com"
           }
         }
       },