Skip to content

Understanding Your Workspace

What is a Workspace?

In Centrali, a workspace is your isolated environment where all your application's data, functions, and configurations live. When you sign up for Centrali, you get a workspace with a unique identifier that's used in all API calls.

Your Workspace Identifier

Every API call includes your workspace identifier in the URL:

https://api.centrali.io/data/workspace/{your-workspace}/api/v1/records

For example, if your workspace is acme-corp: 

https://api.centrali.io/data/workspace/acme-corp/api/v1/records

What's In Your Workspace?

Your workspace contains:

  • Structures - Your data schemas (like database tables), with support for secret fields and validation
  • Records - Your actual data entries with version history
  • Compute Functions - Your serverless business logic (JavaScript)
  • Triggers - Automation rules that react to data changes, schedules, or webhooks
  • Orchestrations - Multi-step workflows that chain functions with conditional logic, delays, and decision branches
  • Files - Uploaded files and assets managed via secure storage
  • Search - Full-text search across your data with faceted search and fuzzy matching
  • Notifications - Real-time WebSocket notifications for workspace events
  • Real-Time Events - Server-Sent Events (SSE) streaming for live data updates
  • External Auth Providers - BYOT (Bring Your Own Token) configuration for Clerk, Auth0, Okta, and other OIDC providers
  • AI Features - AI-powered data validation, anomaly detection, and schema discovery
  • Service Accounts - Machine-to-machine API credentials
  • Groups & Permissions - Fine-grained access control with policies

Workspace Isolation

Everything in your workspace is completely isolated: - Your data is private and secure - Service account credentials and JWT tokens are scoped to your workspace - Functions can only access your workspace's data - No cross-workspace data access

Using Your Workspace

In API Calls

Always include your workspace identifier. All API requests require a JWT token obtained via your service account credentials or an external token (BYOT) when configured:

const workspace = 'your-workspace';
const apiUrl = `https://api.centrali.io/data/workspace/${workspace}/api/v1`;

// Create a record (using JWT token from service account)
fetch(`${apiUrl}/records/slug/products`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    data: { name: 'Widget', price: 99.99 }
  })
});

Using the Query Language

Centrali provides a powerful query system for filtering, sorting, searching, and paginating your data:

// Filter with operators using bracket notation
fetch(`${apiUrl}/records/slug/products?data.price[gte]=50&data.inStock=true&sort=-createdAt&page=1&pageSize=25`, {
  headers: { 'Authorization': 'Bearer YOUR_JWT_TOKEN' }
});

See the Query Guide for full syntax and the Query Cheatsheet for quick reference.

In the Console

When you log into the Centrali Console, you're automatically in your workspace context. All operations in the UI apply to your workspace.

API Authentication

Centrali uses JWT tokens for API authentication. There are two ways to obtain tokens:

  1. Service Accounts (recommended for API and SDK integrations)
  2. Create a service account in Developers → Service Accounts
  3. Exchange client_id and client_secret for a JWT token via OAuth 2.0 client credentials flow
  4. Tokens are workspace-scoped and expire after 7 hours

  5. See the Service Account Guide for details

  6. External Tokens (BYOT) (for apps with their own identity provider)

  7. Pass JWTs from Clerk, Auth0, Okta, or any OIDC provider directly to Centrali
  8. Centrali validates the token and uses its claims for authorization
  9. See the External Auth Guide for details

Best Practices

  1. Keep your workspace identifier handy - You'll use it in every API call
  2. Secure your service account credentials - Store client_id and client_secret safely
  3. Use environment variables - Store credentials as environment variables:
# .env file (never commit to git!)
CENTRALI_WORKSPACE=your-workspace
CENTRALI_CLIENT_ID=ci_your_client_id
CENTRALI_CLIENT_SECRET=sk_your_client_secret

// In your code
const workspace = process.env.CENTRALI_WORKSPACE;
const clientId = process.env.CENTRALI_CLIENT_ID;
const clientSecret = process.env.CENTRALI_CLIENT_SECRET;

Summary

Your workspace is your private space in Centrali where you build your application. All you need to remember is: - Your workspace identifier (used in API URLs) - Your service account credentials (for API authentication) - Everything you create stays in your workspace — data, functions, orchestrations, files, and configurations are all isolated

Ready to start building? Head to the Quick Start Guide to create your first structure and records.