CloudScale FAQ

No. Catalyst CloudScale Authentication doesn’t offer single sign-on across Catalyst applications. Each application keeps its own users: a person who signs up to two of your applications gets a separate identity, with its own ZUID and Org ID, in each one, and signs in to each separately. A user’s sign-in token from one project can’t call another project’s protected functions.

What you can do instead:

1. Put apps that must share their users in one Catalyst project, so they use one set of users.
2. Enable the same social login, such as Zoho, Google or Microsoft 365, in every application, so users sign in everywhere with the same provider account instead of a separate password.
3. Use Third-party Authentication with an identity provider that offers single sign-on. The provider verifies the user, and your function in each project creates the Catalyst session with a custom token (generateCustomToken()).

Note: Social logins and Third-party Authentication require Public Signup to be enabled.

Refer to the Users help page for how user identities work across applications.

No. In Catalyst CloudScale Authentication, social logins, including Zoho, are available only while Public Signup is enabled, and so is Custom User Validation. With Public Signup off, you add users yourself from User Management, and they sign in with the password they set for your app.

To let only named employees in with their Zoho accounts:

1. Enable Public Signup and the Zoho social login in CloudScale → Authentication.
2. Write a Basic I/O function that reads the sign-up request and returns status: "failure" for any email address that isn’t on your allow-list.
3. In Authentication → Whitelisting, turn on Custom User Validation, select the function and click Configure.
4. To remove someone’s access later, disable or delete them in User Management → Users, because Custom User Validation runs only when a user signs up, not at each sign-in.

Note: Catalyst doesn’t offer a sign-in limited to one company’s Zoho organization, and a Zoho sign-in creates a new app user rather than linking to a user you invited with the same email address.

Refer to the Custom User Validation help page for details.

Catalyst CloudScale Data Store allows up to 100 columns in each table by default. Catalyst support can raise this for a table on request, case by case and up to a maximum. When a table reaches its limit, creating a column fails with an API limit error, which can mention the table limit even though the column limit was reached.

1. Check whether the table needs that many columns. Repeating groups of fields often work better as a child table linked by a Foreign Key column.

2. To ask for more, contact Catalyst support with your project, the Table ID of each table, how many columns you need and what the table is for.

3. A raise applies to the tables you name. Ask again for tables you create later.

4. When Support confirms the raise, refresh the console and add the columns.

Note: Text, Var Char and Encrypted Text columns also have a combined limit per table, which a raise of the total column limit doesn’t change.

Refer to the Columns help page for more information.

You will encounter this error if you have not initialized the Catalyst Node.js SDK properly in your function. Follow the steps listed below to ensure you have initialized the Node.js SDK and Data Store properly.

const catalyst = require(“zcatalyst-sdk-node”);
const datastore = catalystApp.datastore(); //Initializing catalystApp variable differs with each function type

This happens when too many requests to a Catalyst CloudScale component, such as Data Store (including ZCQL queries) or NoSQL, run at the same moment. Catalyst returns HTTP 429 TOO_MANY_REQUESTS for the requests above the limit. It can appear even when your functions or AppSail service handle the load, because the component has its own concurrency limit.

1. Send fewer requests at once: combine lookups into one ZCQL query, insert several rows in one insertRows() call, and avoid one query per record inside a loop.
2. Keep values you read often in Catalyst CloudScale Cache instead of querying them each time.
3. Retry refused requests after a short delay that grows with each attempt.
4. If you still need more simultaneous operations, contact Catalyst support with the environment, the component, the error text and time, and your expected peak number of simultaneous operations.

Refer to the Error Codes help page for details.

You can add a key-value pair to a cache segment from the Catalyst console, or using the Java SDK, Node SDK, Python SDK or the Insert a Key-Value Pair In a Cache Segment API.

You can retrieve a value from the cache segment using the Get the Value of a Cache Key API, and Java SDK, Node SDK, and Python SDK.

If you enabled the API Key-based authentication, the authentication is handled by an API key generated by Catalyst for your project automatically. You need to pass the API Key value with the keyname ZCFKEY along with the request header or as a query parameter.

The API Key is the same for all projects in the development environment. When you deploy a Catalyst project to the production environment, Catalyst will provide you a different API key for production. You will therefore have individual API keys for each project in the production environment.

To resolve this error, check if the domain that you want to map with a Catalyst application is already hosted live in your domain provider’s hosting site and then follow the steps below:

Step 1: Create a CNAME record for your domain in your DNS configuration by adding your subdomain’s value as the Host Name/Alias/CNAME.

For example, if your domain address is “portal.zylker.com”, you must add “portal” as the Host Name/Alias/CNAME value and “catalyst.cs.zohohost.com” as the Destination/Points To value.

Add the domain name in the Catalyst console. Now the process will move to the next step -> Verify Ownership.

Step 2: Catalyst will now generate a unique hash key value for the specific mapping.

Create a new CNAME record for your domain in your DNS configuration and add the following values: hash_key.subdomain as Host Name/Alias/CNAME

For example, if the hash key generated by Catalyst is “c12to00001x11pl1234h9e33w44h6789”, and the subdomain is “portal”, you must enter the Host Name as “c12to00001x11pl1234h9e33w44h6789.portal”.

Note: Ensure that you specify the subdomain “catalyst.cs.zohohost.com” as the Destination/Points To value. The changes might take some time to reflect on the DNS server. After the changes are reflected, this will verify your ownership of the domain in Catalyst. You can find the help documentation for the same here.

No. Catalyst CloudScale Domain Mappings maps only subdomains, such as www.zylker.com or app.zylker.com, because a mapping works through CNAME records and Catalyst does not support mapping a base domain directly to an application URL. Catalyst also does not give you IP addresses to use in A or AAAA records. Map a subdomain, then redirect the root domain to it at your DNS provider.

1. If you added the root domain in Domain Mappings, delete that mapping.

2. Switch to the Production environment, open Domain Mappings under Host and Manage and click Add Mapping. Enter a subdomain such as www.zylker.com. For an AppSail app, select AppSail as the domain type.

3. Add the two CNAME records the console shows, with the subdomain as the host name, and click Verify.

4. At your DNS provider, set up domain forwarding from zylker.com to www.zylker.com over HTTPS.

Note: Requests to the root domain never reach Catalyst, so your DNS provider serves the redirect and any certificate for the root domain. If it cannot forward over HTTPS, ask the provider which option it offers.

Refer to the Domain Mappings: Implementation help page for more information.

You can’t edit the scopes of a Catalyst CloudScale Connection once it is created, and you can’t edit its Connection Link Name either. To use different scopes, create a new Connection:

1. Open your project in the Catalyst console, go to CloudScale → Connections and click Create Connection.
2. Choose the same service, enter a name, select every scope your code needs, click Create And Connect and authorize the connection.
3. Update your code to use the new Connection Link Name, and deploy it.
4. Delete the old Connection: click its ellipsis icon, click Delete, then Yes, Delete.

If you delete the old Connection first, you can create the new one with the same name so your code doesn’t change, but calls that use it fail until the new Connection is authorized.

Note: Only the developer who established a Connection can edit or delete it; anyone else must revoke it and establish it again first.

Refer to the Manage Connections help page for details.

In Catalyst CloudScale Mail, a domain is authenticated only when Catalyst finds both the SPF and the DKIM record it generated for that domain in public DNS, exactly as the console shows them. The usual causes are a DKIM record with the wrong host name or value, a second SPF record on the domain, or an SPF value typed by hand.

1. In the Catalyst CloudScale console, go to Notify → Mail → Domain and click Validate for the domain to see its SPF and DKIM codes.

2. Add the DKIM record exactly as shown.

3. Copy the SPF value from the console, not from an example, because it can differ by data center.

4. A domain can have only one SPF record. If one exists for another mail service, add the Catalyst include: value to it instead of adding a second record, keeping one all term at the end. SPF also limits DNS lookups per record, so remove includes you no longer use.

5. Check both records with a public DNS lookup tool, wait for them to propagate, then click Authenticate in the Authenticate Domain pop-up.

Note: If both records are publicly visible and match the console but the domain stays pending, contact Catalyst support with the domain, the project and your data center.

Refer to the Domains help page for more information.

Catalyst CloudScale Mail sends email only after both the sender email address and its domain are verified, and the domain is authenticated with its SPF and DKIM records. Sending before then throws an exception, and no email is sent. A domain that shows pending has not finished one of these steps.

1. Go to Notify → Mail in the Catalyst CloudScale console and open the Domain tab. If your domain isn’t listed, click Add Domain, enter an email address on that domain and click Create.

2. Click Verify Code, enter the code sent to that address and click Confirm.

3. Click Validate, add the SPF and DKIM record codes shown to your domain host’s DNS settings, then click Authenticate.

4. In Email Configuration, click Click to confirm for the sender address, enter the confirmation code and click Confirm.

5. Send again once the domain shows as authenticated and the sender address shows Verified.

Refer to the Domains help page and the Send Emails help page for more information.

In Catalyst CloudScale NoSQL, HTTP 200 only means the request was processed. Whether a conditional write was applied is reported for each item in the response: the status is Success when the item was written, and ConditionMismatch or CriteriaMismatch when the condition was not met and nothing changed.

1. After a conditional update, read each item’s status in the result, for example data.update[0].status from updateItems(), instead of the HTTP status code.

2. Treat a mismatch as “the item is no longer in the state I expected”, for example because another request changed it first. Don’t retry the same write blindly.

3. Build the condition on values you read, such as a version attribute, so that only one of several concurrent writers succeeds. A conditional write to a single item is applied atomically.

4. To check the item afterwards, read it with consistent_read set to true, which reads from the master. A key that doesn’t exist returns a successful response with no items.

Note: Conditions apply to one item at a time. NoSQL has no transactions across items, and a write that times out on the client has no confirmed outcome until you read the item again.

Refer to the Update Item help page and the Query Table help page for more information.

Not directly. Catalyst CloudScale Web Client Hosting serves your web client under the /app/ path, also on a mapped custom domain. To serve it from the root, including files such as robots.txt or a sitemap, route requests through Catalyst CloudScale API Gateway:

1. Plan first: when you enable API Gateway, Security Rules are disabled and all your function and web client URLs are inaccessible until you create APIs for them. API Gateway is a paid component.
2. Open CloudScale → API Gateway (under Security & Identity), click Enable Now, then Proceed.
3. Create APIs for all your functions. Auto-create is available only until you create your first API.
4. Click Create API, select GET, enter the request URL /{path:(.*)}, select the web client as the target, append {path} to its target URL /app/, and click Create.
5. Test the default application URL and your custom domain.

Alternatively, host the site on Catalyst Slate, Catalyst’s frontend hosting service.

Refer to the API Gateway Key Concepts help page and the Web Client Hosting Introduction help page for details.