# Return Nova account SSO URL

This function ensures that an AI App Builder account exists for the
caller, then returns an SSO URL. The system reuses existing accounts.
For entitled accounts of any tier, the system usually provisions the
account eagerly, asynchronously, during account creation or package
upgrades. This function is a fail-safe: it provisions the account on
the spot for any entitled caller the eager provisioning hasn't
already covered.

Note:

  This function requires that your package includes the AI App Builder feature.

Important:

  When you disable the AI App Builder feature, the system disables this function.

Endpoint: GET /Nova/ensure_account
Version: 11.138.0.10
Security: BasicAuth

## Query parameters:

  - `colorScheme` (string)
    The color scheme Meridian is using, so Nova can match it.
    Enum: "light", "dark", "auto"

  - `domain` (string)
    The domain to use for the AI App Builder website.
    Example: "example.com"

  - `promptToken` (string)
    A base64-encoded prompt token to pre-populate the user's website generation goals.
This allows hosting companies to collect user intent before SSO and pass it through
to the Nova interface.

Requirements:

  * Valid base64 encoding — You can use standard or URL-safe variants.
  * Maximum 5000 characters after the system decodes it.
  * Non-empty content — The system ignores empty or whitespace-only prompts.


Example use case:

  A hosting company builds a custom landing page that asks, "What kind of website
  do you want to create?" The user's response is base64-encoded and passed via
  this parameter, allowing Nova to use it as the initial generation prompt.
    Example: "SSB3YW50IHRvIGNyZWF0ZSBhIHBvcnRmb2xpbyB3ZWJzaXRlIGZvciBteSBwaG90b2dyYXBoeSBidXNpbmVzcw=="

  - `return_url` (string)
    Where Nova's "Back to cPanel" control returns the user. Required for a
regular account and rejected for a standalone one. Must be an https URL
of at most 2048 characters, on the host the request was made to, with
the path "/frontend/meridian/index.html" (optionally prefixed by a
cPanel session token) and the in-product route in the fragment.
    Example: "https://cpanel-server.tld:2083/frontend/meridian/index.html#/websites"

## Response 200 fields (application/json):

  - `apiversion` (integer)
    The version of the API.
    Example: 3

  - `func` (string)
    The name of the method called.
    Example: "ensure_account"

  - `module` (string)
    The name of the module called.
    Example: "Nova"

  - `result` (object)

  - `result.data` (object)

  - `result.data.created` (integer)
    Whether the system created a new AI App Builder account.
    Enum: 1, 0

  - `result.data.sso_url` (string)
    The SSO link to the AI App Builder.
    Example: "https://my.sitehub.io/website/edit?ssotoken=example"

  - `result.errors` (array,null)
    List of errors if the API failed.

  - `result.messages` (array,null)
    List of messages generated by the API.

  - `result.metadata` (object)

  - `result.metadata.transformed` (integer)
    Post-processing may have transformed the data.
    Enum: 1

  - `result.status` (integer)
    - 1 - Success.
- 0 - Failed: Check the errors field for more details.
    Enum: 1, 0

  - `result.warnings` (array,null)
    List of warnings generated by the API. Warnings describe non-critical failures or other problematic conditions noted while running an API.