Account Setup Guide¶

Welcome to Centrali! This guide will help you get your account set up and ready to start building.

Step 1: Create Your Centrali Account¶

Visit centrali.io to create your account.

1. Click the "Sign Up" button on the landing page
2. Fill in your account details
3. Verify your email address
4. Complete the onboarding flow

For pricing information and plan details, visit the Centrali pricing page.

Step 2: Create Your First Workspace¶

After signing in to the Centrali dashboard:

1. Navigate to Workspaces

2. Click "Create Workspace" or "New Workspace"

3. Configure Your Workspace

4. Workspace Name: A friendly name for your project (e.g., "My App Production")

5. Workspace Slug: A unique identifier used in API URLs (e.g., my-app-prod)

   • Must be lowercase letters, numbers, and hyphens only
   • Cannot be changed after creation
   • Example: my-app-prod becomes https://api.centrali.io/data/workspace/my-app-prod/...

6. Select Your Plan

7. Choose the plan that fits your needs

8. You can upgrade or downgrade later

9. Create Workspace

10. Click "Create" to finalize

What is a Workspace?

A workspace is an isolated environment for your application. Each workspace has: - Separate data: Structures and records are isolated - Separate billing: Each workspace is billed independently - Separate team access: Invite team members per workspace - Separate credentials: Service accounts are workspace-scoped

You can create multiple workspaces for different projects or environments (e.g., my-app-dev, my-app-staging, my-app-prod).

Step 3: Create a Service Account¶

Service accounts are the recommended way to authenticate with Centrali's API and SDK.

What is a Service Account?¶

A service account is a machine-to-machine authentication method that: - Works for API and SDK: Use the same credentials for all integrations - Is workspace-scoped: Each workspace has its own service accounts - Can be rotated: Regenerate credentials without changing code - Has fine-grained permissions: Control what each service account can do (coming soon)

Creating Your First Service Account¶

From the Dashboard:

1. Navigate to Your Workspace

2. Select the workspace you just created

3. Go to Settings → Service Accounts

4. Click "Settings" in the sidebar

5. Navigate to "Service Accounts" tab

6. Create Service Account

7. Click "Create Service Account"
8. Enter a descriptive name (e.g., "Development", "Production API", "CI/CD")

9. Optionally add a description

10. Save Your Credentials

11. You'll receive a client_id and client_secret
12. ⚠️ Important: The client_secret is shown only once!
13. Copy both values and store them securely

Example Credentials:

client_id: ci_a1b2c3d4e5f6g7h8i9j0
client_secret: sk_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Storing Credentials Securely¶

Development: Use environment variables:

# .env file (never commit to git!)
CENTRALI_CLIENT_ID=ci_a1b2c3d4e5f6g7h8i9j0
CENTRALI_CLIENT_SECRET=sk_0123456789abcdef...
CENTRALI_WORKSPACE=my-app-prod

Production: Use a secrets management service: - AWS Secrets Manager - Google Secret Manager - Azure Key Vault - HashiCorp Vault - Your platform's environment variables (Vercel, Netlify, Railway, etc.)

Never: - ❌ Commit credentials to git - ❌ Hardcode in source code - ❌ Share via email or chat - ❌ Store in plain text files

Step 4: Test Your Setup¶

Verify your service account works with a simple API call:

# Set your credentials
export CENTRALI_CLIENT_ID="ci_your_client_id"
export CENTRALI_CLIENT_SECRET="sk_your_client_secret"
export CENTRALI_WORKSPACE="your-workspace-slug"

# Get an access token
curl -X POST "https://auth.centrali.io/oidc/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CENTRALI_CLIENT_ID" \
  -d "client_secret=$CENTRALI_CLIENT_SECRET" \
  -d "scope=openid"

Expected Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 25200,
  "scope": "openid"
}

If you receive a token, you're all set! 🎉

Step 5: Use the SDK (Recommended)¶

The Centrali SDK handles authentication automatically:

npm install @centrali-io/centrali-sdk

import { CentraliSDK } from '@centrali-io/centrali-sdk';

const centrali = new CentraliSDK({
  baseUrl: 'https://api.centrali.io',
  workspaceId: process.env.CENTRALI_WORKSPACE,
  clientId: process.env.CENTRALI_CLIENT_ID,
  clientSecret: process.env.CENTRALI_CLIENT_SECRET
});

// The SDK automatically fetches and manages tokens
// You can now make API calls:
const structures = await centrali.queryRecords('Product', {
  limit: 10
});

See the SDK Guide for complete documentation.

Alternative: Create Service Account via API¶

If you prefer to automate service account creation, you can use the API.

Prerequisites: - You must be logged in to the Centrali dashboard - You'll need a user session token (from browser cookies)

See the Service Account Authentication Guide for detailed API instructions.

Next Steps¶

Now that your account is set up:

1. Quick Start Guide - Build your first API in 10 minutes
2. Understanding Your Workspace - Learn about workspace concepts
3. Authentication Overview - Understand authentication flows
4. SDK Guide - Learn to use the official SDK

Troubleshooting¶

Can't create a workspace¶

• Check your account status: Ensure your email is verified
• Plan limits: Free tier may have workspace limits
• Contact support: Reach out if issues persist

Service account credentials not working¶

• Check credentials: Ensure no extra spaces or line breaks
• Verify workspace: Credentials are workspace-specific
• Token endpoint: Must use https://auth.centrali.io/oidc/token
• See troubleshooting: Authentication Troubleshooting

Lost client_secret¶

• Cannot retrieve: Client secrets are shown only once during creation
• Solution: Rotate the service account to get a new secret
• In dashboard: Settings → Service Accounts → [Your Account] → Rotate Secret

Security Best Practices¶

✅ Do: - Store credentials in environment variables or secret managers - Use separate service accounts for dev/staging/production - Rotate credentials regularly (every 90 days recommended) - Use different service accounts for different applications - Monitor service account usage for unusual activity

❌ Don't: - Commit credentials to version control - Share credentials via email or messaging - Use the same credentials across all environments - Give service accounts more permissions than needed

Getting Help¶

• Documentation: API Reference
• Examples: Quick Start
• Authentication: Service Account Guide
• Support: Contact your workspace administrator or Centrali support

Ready to build? Head to the Quick Start Guide! →