Skip to content

Identifier Reference

This page documents every identifier type in Centrali, what it looks like, where you use it, and common mistakes to avoid.

Quick Reference

Identifier Format Example Where Used
Workspace slug Lowercase string, hyphen-separated acme-corp URL paths, SDK config
Workspace ID UUID v4 a3b1c2d4-5678-4abc-9def-0123456789ab Internal only
Collection ID UUID v4 d4e5f6a7-8901-4bcd-ef23-456789abcdef Console UI, API DELETE /collections/:id
Collection slug (recordSlug) Lowercase string, auto-generated from name blog-posts SDK methods, record API paths
Record ID UUID v4 f1a2b3c4-5678-4def-9012-abcdef345678 Record CRUD operations
User ID UUID v4 b2c3d4e5-6789-4abc-def0-123456789abc Token claims (sub), audit trails
Service account ID Auto-incrementing integer 42 Console API route parameter (:cid)
Client ID Prefixed string: ci_ + 24 hex chars ci_a1b2c3d4e5f6a7b8c9d0e1f2 OAuth token requests
Client secret Prefixed string: sk_ + 64 hex chars sk_aabbccdd... (64 hex chars) OAuth token requests (shown once)
Publishable key Prefixed string: pk_live_ + random chars pk_live_x7k9m2p4... Browser-safe frontend API calls
Function ID UUID v4 e5f6a7b8-9012-4cde-f345-6789abcdef01 Function CRUD, trigger config
Trigger ID UUID v4 c3d4e5f6-7890-4abc-def1-234567890abc Trigger management, run tracking
Function run ID UUID v4 a1b2c3d4-5678-4901-bcde-f01234567890 Run logs, re-runs
Execution ID UUID v4 d4e5f6a7-8901-4234-bcde-f56789abcdef Loop prevention, compute gateway tracking
Job ID String job_abc123 Compute gateway dispatch
Orchestration ID Prefixed xid: orch_ + 20 chars orch_ctb5h4l6n7m8p9q0r1s2 Automation CRUD
Orchestration run ID Prefixed xid: orun_ + 20 chars orun_ctb5h4l6n7m8p9q0r1s2 Run tracking
Orchestration step ID Prefixed xid: ostep_ + 20 chars ostep_ctb5h4l6n7m8p9q0r1s2 Step tracking
Orchestration slug Lowercase string onboard-new-customer Unique per workspace
Page ID UUID v4 b8c9d0e1-2345-4abc-def6-789012345678 Page CRUD
Page version ID UUID v4 e1f2a3b4-5678-4cde-f901-234567890abc Version management
Page slug Lowercase string team-dashboard Unique per workspace, used in page URLs

Workspace Identifiers

Workspace Slug

  • Format: Lowercase string with hyphens (e.g. acme-corp, my-workspace)
  • Where used: Every API URL path, SDK configuration, database queries for tenant isolation
  • Set at: Workspace creation. Cannot be changed.
# Workspace slug appears in every API URL
curl https://api.centrali.io/data/workspace/acme-corp/api/v1/collections \
  -H "Authorization: Bearer $TOKEN"

const centrali = new CentraliSDK({
  workspaceId: 'acme-corp',  // This is the workspace slug
  // ...
});

Common mistake

The SDK option is called workspaceId but it takes the workspace slug, not the UUID. This is a naming legacy. Always pass the slug (e.g. acme-corp), never the UUID.

Workspace ID

  • Format: UUID v4 (e.g. a3b1c2d4-5678-4abc-9def-0123456789ab)
  • Where used: Internal database primary key. You will rarely need this directly.
  • Generated by: PostgreSQL gen_random_uuid() at creation time.

Collection Identifiers

Collections (formerly called "structures") have two identifiers you will encounter.

Collection ID (structureId)

  • Format: UUID v4 (e.g. d4e5f6a7-8901-4bcd-ef23-456789abcdef)
  • Where used: Console UI references, delete/update API calls by ID, internal foreign keys
  • Generated by: PostgreSQL gen_random_uuid() at creation time
# Delete a collection by ID
curl -X DELETE \
  "https://api.centrali.io/data/workspace/acme-corp/api/v1/collections/d4e5f6a7-8901-4bcd-ef23-456789abcdef" \
  -H "Authorization: Bearer $TOKEN"

Collection Slug (recordSlug)

  • Format: Lowercase hyphenated string, auto-generated from the collection name (e.g. blog-posts, order-items)
  • Where used: Record API paths, SDK methods, event-driven trigger config, realtime event filtering
  • Set at: Collection creation. Auto-generated from name if not provided. Must be unique within the workspace.
// SDK uses the collection slug (recordSlug) for record operations
const records = await centrali.queryRecords('blog-posts', {
  'data.published': true,
});

const record = await centrali.getRecord('blog-posts', 'rec-uuid-here');

# Record API paths use the collection slug
curl "https://api.centrali.io/data/workspace/acme-corp/api/v1/records/slug/blog-posts" \
  -H "Authorization: Bearer $TOKEN"

Common mistake: recordSlug vs collection name

The database column is called recordSlug for historical reasons -- it is the collection slug. It is not the same as the collection name (which can contain spaces and uppercase). When referring to a collection in API paths or SDK calls, always use the slug.

Tip

You can find a collection's slug in the console under the collection settings, or by calling GET /collections and reading the recordSlug field.

Record Identifiers

Record ID

  • Format: UUID v4 (e.g. f1a2b3c4-5678-4def-9012-abcdef345678)
  • Where used: Record CRUD operations (get, update, delete)
  • Generated by: PostgreSQL gen_random_uuid() at creation time
// Get a specific record by ID
const order = await centrali.getRecord('orders', 'f1a2b3c4-5678-4def-9012-abcdef345678');

// Update a record by ID
await centrali.updateRecord('orders', 'f1a2b3c4-5678-4def-9012-abcdef345678', {
  data: { status: 'shipped' },
});

Note

Records are always accessed through their parent collection slug. You cannot look up a record by ID alone -- you need both the collection slug and the record ID.

Auth Identifiers

User ID

  • Format: UUID v4 (e.g. b2c3d4e5-6789-4abc-def0-123456789abc)
  • Where used: JWT token sub claim, createdBy/updatedBy fields, audit trails
  • Generated by: PostgreSQL gen_random_uuid() at user creation

Service Account ID (numeric)

  • Format: Auto-incrementing integer (e.g. 42, 107)
  • Where used: Console API route parameter (:cid) for managing service accounts (rotate secret, revoke, delete)
  • Generated by: PostgreSQL bigIncrements on the oidc_clients table
# Rotate a service account's secret (uses numeric ID)
curl -X PUT \
  "https://api.centrali.io/iam/workspace/acme-corp/api/v1/service-accounts/42/rotate" \
  -H "Authorization: Bearer $TOKEN"

Client ID (clientId)

  • Format: ci_ prefix + 24 hex characters (e.g. ci_a1b2c3d4e5f6a7b8c9d0e1f2)
  • Where used: OAuth client_credentials token requests, SDK configuration
  • Generated at: Service account creation. Visible in the console and API response.

Client Secret (clientSecret)

  • Format: sk_ prefix + 64 hex characters
  • Where used: OAuth client_credentials token requests, SDK configuration
  • Generated at: Service account creation. Shown only once. If lost, you must rotate to get a new one.
const centrali = new CentraliSDK({
  workspaceId: 'acme-corp',
  clientId: 'ci_a1b2c3d4e5f6a7b8c9d0e1f2',       // Client ID
  clientSecret: 'sk_aabbccdd...',                    // Client Secret
  authDomain: 'https://auth.centrali.io',
  apiBaseDomain: 'https://api.centrali.io',
});

Common mistake: service account ID vs client ID

The service account ID (42) is the numeric database row ID used in console management API routes. The client ID (ci_a1b2c3...) is the OAuth credential string used for token requests and SDK config. These are different values on the same service account.

Publishable Key

  • Format: pk_live_ prefix + random characters (e.g. pk_live_x7k9m2p4q5r6s7t8)
  • Where used: Browser-safe frontend API calls with scoped permissions
  • Generated at: Key creation. Shown only once. The full key is never stored (only a SHA-256 hash and the prefix are kept).

Function & Trigger Identifiers

Function ID

  • Format: UUID v4 (e.g. e5f6a7b8-9012-4cde-f345-6789abcdef01)
  • Where used: Function CRUD, trigger configuration (functionId field), run tracking
  • Generated by: PostgreSQL gen_random_uuid() at function creation

Trigger ID

  • Format: UUID v4 (e.g. c3d4e5f6-7890-4abc-def1-234567890abc)
  • Where used: Trigger management, function run source tracking, on-demand invocation
  • Generated by: PostgreSQL gen_random_uuid() at trigger creation

Function Run ID

  • Format: UUID v4 (e.g. a1b2c3d4-5678-4901-bcde-f01234567890)
  • Where used: Viewing run logs, triggering re-runs, linking to orchestration steps
  • Generated by: PostgreSQL gen_random_uuid() at run creation

Execution ID

  • Format: UUID v4
  • Where used: Internally by the compute gateway for loop prevention and run correlation. Each function execution gets a unique execution ID.

Relationship between function, trigger, and run

A function contains your code. A trigger defines when that function runs (and references a functionId). A run is a single execution of a function (and references both functionId and triggerId).

Orchestration Identifiers

Orchestration IDs use a prefixed xid format (not UUID). The xid library generates globally unique, sortable, 20-character identifiers.

Orchestration ID

  • Format: orch_ + 20-character xid (e.g. orch_ctb5h4l6n7m8p9q0r1s2)
  • Where used: Automation CRUD, run creation, history tracking

Orchestration Slug

  • Format: Lowercase string (e.g. onboard-new-customer)
  • Where used: Human-readable reference. Unique per workspace.

Orchestration Run ID

  • Format: orun_ + 20-character xid (e.g. orun_ctb5h4l6n7m8p9q0r1s2)
  • Where used: Run tracking, step listing, failure investigation

Orchestration Run Step ID

  • Format: ostep_ + 20-character xid (e.g. ostep_ctb5h4l6n7m8p9q0r1s2)
  • Where used: Individual step tracking within a run
# List runs for an orchestration
curl "https://api.centrali.io/orchestration/workspace/acme-corp/api/v1/orchestrations/orch_ctb5h4l6n7m8p9q0r1s2/runs" \
  -H "Authorization: Bearer $TOKEN"

# Get steps for a specific run
curl "https://api.centrali.io/orchestration/workspace/acme-corp/api/v1/runs/orun_ctb5h4l6n7m8p9q0r1s2/steps" \
  -H "Authorization: Bearer $TOKEN"

Orchestration IDs look different from other IDs

Orchestration IDs use prefixed xids (orch_, orun_, ostep_), not UUIDs. This makes them easy to identify at a glance and sortable by creation time.

Page Identifiers

Page ID

  • Format: UUID v4 (e.g. b8c9d0e1-2345-4abc-def6-789012345678)
  • Where used: Page CRUD, version management, publication
  • Generated by: PostgreSQL gen_random_uuid() at page creation

Page Slug

  • Format: Lowercase string (e.g. team-dashboard, new-employee-form)
  • Where used: Page URLs at runtime, unique per workspace (excluding soft-deleted pages)

Page Version ID

  • Format: UUID v4 (e.g. e1f2a3b4-5678-4cde-f901-234567890abc)
  • Where used: Version-specific operations (publish, view draft vs published)
  • Generated by: PostgreSQL gen_random_uuid() at version creation

Each page also has a sequential version number (integer) that increments with each new version.

Common Mistakes

Mistake Explanation
Passing workspace UUID where slug is expected API paths and SDK config expect the slug (acme-corp), not the UUID
Using collection name instead of collection slug The name "Blog Posts" is not the slug blog-posts. Use recordSlug from the API response.
Confusing service account ID (42) with client ID (ci_...) The numeric ID is for management APIs. The ci_ string is for OAuth token requests.
Using a UUID for an orchestration ID Orchestration IDs are prefixed xids (orch_...), not UUIDs
Looking up a record without the collection slug Record endpoints require both the collection slug and the record ID in the path
Assuming publishable keys can be recovered Full publishable keys are shown once at creation. Only the prefix (pk_live_ + 8 chars) is stored.