skills/catalyst-by-zoho/references/meta-ids.md

# Catalyst Meta IDs: Complete Reference

Every Catalyst component uses unique identifiers. This reference explains what each ID is, where to
find it, and when you need it. When writing code that references any of these IDs, always tell the
user where to find the value — never leave a placeholder unexplained.

---

## Table of Contents
1. [Project-Level IDs](#project-level-ids)
2. [Environment & Authentication IDs](#environment--authentication-ids)
3. [Data & Storage IDs](#data--storage-ids)
4. [Function & Compute IDs](#function--compute-ids)
5. [Service IDs](#service-ids)
6. [User & Identity IDs](#user--identity-ids)
7. [Quick Lookup Table](#quick-lookup-table)
8. [Common Pitfalls](#common-pitfalls)

---

## Project-Level IDs

### Project ID
- **What:** Unique identifier for your Catalyst project, auto-generated at creation.
- **Where to find:**
  - **Console:** Settings → Project Settings → General. Displayed under the project name.
  - **CLI:** Run `catalyst projects:list` — shows a table of project names and IDs.
  - **File:** `.catalystrc` at project root (field `project_id`).
- **When you need it:** API calls, CLI operations, constructing function invocation URLs.
- **Format:** Numeric string, e.g. `"123456789"`.
- **Important:** Do NOT modify `project_id` in `.catalystrc` manually. Use `catalyst project:use`
  to switch projects.

```json
// .catalystrc (auto-generated by `catalyst init`)
{
  "project_id": "123456789",
  "project_domain": "myapp-60019947973.development",
  "env_id": "60019947973",
  "timezone": "Asia/Kolkata"
}
```

### Project Domain Name
- **What:** Unique domain name generated when you host a web client (e.g. `shipmenttracking-57673975`).
- **Where to find:** Console → Settings → Environments → General tab → Application URL. Also visible
  in Web Client Hosting.
- **Format:** `{project-name}-{numeric-suffix}`.
- **Used in:**
  - Development URL: `https://{domain}.development.catalystserverless.com`
  - Production URL: `https://{domain}.catalystserverless.com`

---

## Environment & Authentication IDs

### ZAID (Zoho Application ID)
- **What:** Unique portal ID that maps your application to a project and environment. **Critical:**
  the ZAID is **different** in Development and Production environments.
- **Where to find:**
  - **Console:** Settings → Environments → General tab. Both Dev and Prod ZAIDs shown here.
  - **Social Login pop-up:** Also displayed in the social login configuration pop-up.
  - **Web SDK init:** Auto-populated by `/__catalyst/sdk/init.js` when hosted on Catalyst.
- **When you need it:**
  - User registration via SDK (`signupConfig.zaid`)
  - Social login configuration (redirect URIs include ZAID)
  - Password reset via SDK
  - Constructing social login callback URIs:
    `https://{appdomain}/accounts/pfs/{zaid}/clientidpcallback`
- **Format:** Numeric string, e.g. `"1011958529"`.
- **Type:** Always pass ZAID as a string, even though it appears numeric. JavaScript loses
  precision on integers larger than 2^53, and Catalyst IDs can exceed this threshold.
- **Critical gotcha:** When migrating to production, you MUST reconfigure social logins with the
  **Production ZAID** and production app domain. Forgetting this is a common cause of auth failures
  in production.

```javascript
// Node.js — User registration requires ZAID
const signupConfig = {
  platform_type: 'web',
  zaid: '10014774358'  // ← Get from Settings → Environments (always a string)
};
const userConfig = {
  last_name: 'Burrows',
  email_id: 'emma@example.com'
};
let userManagement = catalystApp.userManagement();
await userManagement.registerUser(signupConfig, userConfig);
```

```python
# Python — User registration requires ZAID
signup_config = {
    "platform_type": "web",
    "zaid": "81008807534807534"  # ← Get from Settings → Environments
}
user_details = {
    "first_name": "Amelia",
    "last_name": "Burrows",
    "email_id": "amelia@example.com"
}
authentication_service = app.authentication()
response = authentication_service.register_user(signup_config, user_details)
```

### API Key (API Gateway)
- **What:** Authentication key for the API Gateway feature.
- **Where to find:** Console → Settings → Environments → General tab.
- **Scope:** Common across all projects in Development, but **unique per project** in Production.
- **When you need it:** API Gateway requests requiring key-based authentication.

---

## Data & Storage IDs

### Table ID
- **What:** Unique ID auto-generated when you create a Data Store table.
- **Where to find:** Console → Cloud Scale → Data Store → click on a table. The Table ID is displayed
  under the table name.
- **When you need it:** SDK calls that reference tables by ID instead of name.
- **Format:** Numeric, e.g. `1510000000110121`.
- **Note:** You can use either Table ID or Table Name in SDK calls. Name is more readable but
  case-sensitive. ID is safer for avoiding case-sensitivity issues.

```javascript
// Access table by name (case-sensitive — must match console exactly)
const table = catalystApp.datastore().table('Employees');

// Access table by ID (from Console → Data Store → click table)
const table = catalystApp.datastore().table(1510000000110121);
```

### ROWID
- **What:** Auto-increment unique row identifier, system column in every Data Store table.
- **Where to find:** Returned in query results, visible in Data Store console when viewing rows.
- **When you need it:** Update, delete, and get operations all require ROWID. Pagination uses ROWID.
- **Format:** BigInt, e.g. `"12345"`.
- **Important:** ROWID is auto-managed. Never set it manually on insert — it's assigned by Catalyst.

### Column ID
- **What:** Each column in a Data Store table has a unique ID.
- **Where to find:** Console → Data Store → click table → column details.
- **When you need it:** Rarely needed directly; most SDK calls use column names.

### Folder ID (File Store) — DEPRECATED SERVICE
- **What:** Unique ID for a File Store folder.
- **Where to find:** Console → Cloud Scale → File Store → click folder. ID shown in folder details.
- **When you need it:** All File Store SDK calls (`fileStore.folder(FOLDER_ID)`).
- **Note:** File Store is deprecated (removal date TBD). Use Stratus for new projects.

```javascript
// File Store (deprecated) — Folder ID from Console → File Store → folder details
const folder = catalystApp.filestore().folder(FOLDER_ID);
```

### Bucket Name (Stratus)
- **What:** Name of a Stratus object storage bucket (not a numeric ID — uses string names).
- **Where to find:** Console → Cloud Scale → Stratus → bucket list.
- **When you need it:** All Stratus SDK calls.

```javascript
// Stratus — bucket name from Console → Stratus
const bucket = catalystApp.stratus().bucket('my-bucket');
```

### Segment ID (Cache)
- **What:** Unique ID for a Cache segment.
- **Where to find:** Console → Cloud Scale → Cache → segment list. ID shown next to segment name.
- **When you need it:** All Cache SDK calls (`cache.segment(SEGMENT_ID)`).
- **Format:** Numeric.

```javascript
// Cache — Segment ID from Console → Cache
const segment = catalystApp.cache().segment(SEGMENT_ID);
```

### Collection Name (NoSQL)
- **What:** Name of a NoSQL document collection (string, not numeric ID).
- **Where to find:** Console → Cloud Scale → NoSQL → collection list.
- **When you need it:** All NoSQL SDK calls.

```javascript
// NoSQL — collection name from Console → NoSQL
const collection = catalystApp.nosql().collection('UserProfiles');
```

---

## Function & Compute IDs

### Function ID / Function Name
- **What:** Each function has a unique numeric ID and a name (the directory name).
- **Where to find:** Console → Serverless → Functions → click function. ID shown in function details.
- **When you need it:** REST API calls to invoke functions. CLI operations.
- **Invocation URLs:**
  - Basic I/O: `GET /server/{function_name}/execute?args={input}`
  - Advanced I/O: `ANY /server/{function_name}/{path}`
  - Production Basic I/O: `https://{domain}.catalystserverless.com/baas/v1/project/{project_id}/function/{function_name}/execute`
  - Production Advanced I/O: `https://{domain}.catalystserverless.com/server/{function_name}/`

### AppSail App ID
- **What:** Unique ID for an AppSail application.
- **Where to find:** Console → Serverless → AppSail → app details.
- **When you need it:** CLI deploy commands, API operations.

---

## Service IDs

### Circuit ID
- **What:** Unique ID for a Circuits workflow.
- **Where to find:** Console → Serverless → Circuits → click circuit. ID shown in circuit details.
- **When you need it:** SDK calls to execute circuits, REST API invocations.

```javascript
// Circuits — Circuit ID from Console → Circuits → circuit details
const circuit = catalystApp.circuit();
const result = await circuit.execute(CIRCUIT_ID, { inputKey: 'value' });

// REST API: POST /server/circuit/{circuit_id}/execute
```

### Job Pool ID (Job Scheduling)
- **What:** Unique ID for a job pool.
- **Where to find:** Console → Job Scheduling → pool list. ID shown in pool details.
- **When you need it:** SDK calls to submit jobs to a pool.

```javascript
// Job Scheduling — Pool ID from Console → Job Scheduling → pool details
const pool = catalystApp.jobScheduling().pool(POOL_ID);
await pool.submitJob({ input: JSON.stringify({ taskType: 'report' }) });
```

### Bot ID (ConvoKraft)
- **What:** Unique ID for a ConvoKraft conversational bot.
- **Where to find:** Console → ConvoKraft → bot list. ID shown in bot details.
- **When you need it:** Embedding bots in web applications via JavaScript SDK.

```html
<!-- ConvoKraft — Bot ID from Console → ConvoKraft → bot details -->
<script src="https://static.zohocdn.com/catalyst/sdk/js/convokraft.js"></script>
<script>
  catalyst.convokraft.init({
    botId: 'YOUR_BOT_ID',  // ← Get from Console → ConvoKraft
    position: 'bottom-right'
  });
</script>
```

### Signal/Event IDs
- **What:** IDs for Signals publishers, subscribers, and event routes.
- **Where to find:** Console → Signals → respective component details.

### Pipeline ID
- **What:** Unique ID for a CI/CD pipeline.
- **Where to find:** Console → Pipelines → pipeline details.

---

## User & Identity IDs

### ZUID (Zoho User ID)
- **What:** Unique identification of a Zoho user account, specific to each application.
  A user gets a different ZUID for each Catalyst application they sign up for.
- **Where to find:** Returned in user registration/login API responses. Also visible in
  Console → Authentication → Users → click user.
- **When you need it:** User-specific operations, API calls scoped to a user.
- **Format:** Numeric string, e.g. `"1005641290"`.

### User ID
- **What:** Unique identification of an end-user, limited to Catalyst (not applicable to
  other Zoho services). Auto-created on sign-up.
- **Where to find:** Returned in API responses. Console → Authentication → Users.
- **When you need it:** SDK calls like `getUserDetails(USER_ID)`, `deleteUser(USER_ID)`,
  push notifications to specific users.
- **Format:** Numeric, e.g. `"2305000000007752"`.

### Org ID / ZAAID (Organization ID)
- **What:** Unique identification of the organization an end-user belongs to. Generated when
  a user is added through the Add User API or console. If not specified, Catalyst auto-generates one.
- **Where to find:** Returned in user registration API responses. Console → Authentication → Users
  → user details.
- **When you need it:**
  - Adding users to an existing organization (`addUserToOrg()` method)
  - Multi-org setups where users belong to different organizations
- **Format:** Numeric string, e.g. `"1005641456"`.
- **Important:** An organization cannot be changed once associated with a user account. If a user
  is added by another existing user, they inherit the same Org ID.

```javascript
// Adding user to existing org — requires ZAAID/Org ID
const signupConfig = { platform_type: 'web', zaid: '10014774358' };
const userConfig = {
  last_name: 'Burrows',
  email_id: 'emma@example.com',
  zaaid: '20051993711'  // ← Org ID of existing organization (distinct from ZAID)
};
await userManagement.addUserToOrg(signupConfig, userConfig);
```

### Role ID
- **What:** ID of a user role (e.g., App Admin, App User, or custom roles).
- **Where to find:** Console → Authentication → Roles section. Each role shows its ID.
- **When you need it:** Assigning roles during user registration.
- **Format:** Numeric, e.g. `"2305000000006024"`.

---

## Quick Lookup Table

| ID | What | Where to Find | Format |
|---|---|---|---|
| **Project ID** | Project identifier | Settings → General; `.catalystrc`; `catalyst projects:list` | Numeric string |
| **ZAID** | App-to-environment mapping | Settings → Environments → General tab | Numeric (differs dev/prod!) |
| **API Key** | API Gateway auth key | Settings → Environments → General tab | String |
| **Table ID** | Data Store table | Cloud Scale → Data Store → click table | Numeric |
| **ROWID** | Data Store row | Auto-assigned; returned in queries | BigInt |
| **Folder ID** | File Store folder (deprecated) | Cloud Scale → File Store → folder details | Numeric |
| **Segment ID** | Cache segment | Cloud Scale → Cache → segment list | Numeric |
| **Function ID** | Serverless function | Serverless → Functions → function details | Numeric |
| **Circuit ID** | Circuits workflow | Serverless → Circuits → circuit details | Numeric |
| **Pool ID** | Job Scheduling pool | Job Scheduling → pool details | Numeric |
| **Bot ID** | ConvoKraft bot | ConvoKraft → bot details | String |
| **ZUID** | Zoho user (per-app) | Auth API responses; Authentication → Users | Numeric string |
| **User ID** | Catalyst-only user ID | Auth API responses; Authentication → Users | Numeric |
| **Org ID / ZAAID** | Organization | Auth API responses; Authentication → Users | Numeric string |
| **Role ID** | User role | Authentication → Roles section | Numeric |
| **Bucket Name** | Stratus bucket | Cloud Scale → Stratus | String |
| **Collection Name** | NoSQL collection | Cloud Scale → NoSQL | String |
| **Domain Name** | Project domain | Settings → Environments; Web Client Hosting | String |

---

## Common Pitfalls

1. **ZAID differs between Development and Production.** This is the #1 source of auth issues when
   deploying to production. Always reconfigure social logins, redirect URIs, and any hardcoded
   ZAID references with the Production ZAID after deployment.

2. **The Web SDK `init.js` auto-populates ZAID.** When using `/__catalyst/sdk/init.js`, the ZAID
   is injected automatically based on the environment. You do NOT need to hardcode it. But if
   you're using the SDK programmatically (user registration, password reset), you must pass the
   correct ZAID yourself.

3. **Table names are case-sensitive.** When accessing tables by name, the string must exactly match
   what's in the console. Using the numeric Table ID avoids this issue entirely.

4. **Org ID is permanent.** Once a user is associated with an organization, it cannot be changed.
   Plan your multi-org strategy before adding users.

5. **25-user limit in Development.** You can only add 25 users in the development environment.
   After deploying to production, there's no limit.

6. **Production URLs omit "development" in the path.** Dev URL contains `.development.catalystserverless.com`,
   production URL is just `.catalystserverless.com`. Any hardcoded URLs must be updated.

7. **Don't leave ID placeholders unexplained.** When writing code for the user, always add a comment
   explaining where to find each ID value. Example:
   ```javascript
   // Get TABLE_ID from Console → Cloud Scale → Data Store → click your table
   const table = catalystApp.datastore().table(TABLE_ID);
   ```