Skip to content

Account Setup Guide

Set up a workspace, a service account, and development permissions before starting the Quick Start. You will finish by making an authenticated API request to your workspace.

Step 1: Create Your Account or Accept an Invitation

Starting a new project:

  1. Visit centrali.io and choose Get Started.
  2. Complete signup, including your workspace name. Your account and first workspace are created together.
  3. Open the verification email. Self-serve signup uses email verification followed by automatic sign-in with a magic link into your new workspace.

Joining an existing team:

  1. Ask the workspace administrator to invite your email address.
  2. Follow the invitation email, including password setup if prompted, and sign in.
  3. Select the team's workspace. Do not create a separate workspace for resources that belong to the team.

A workspace isolates your application's data, team access, and credentials. Note its workspace slug, which appears in workspace API URLs. Use the slug, rather than the display name or a workspace UUID, in the examples below.

Step 2: Confirm Your Development Access

Your console login and your service account are separate identities. Giving your login access does not give your application the same permissions.

Identity Development access Who configures it
Your console user workspace_developers for building in an existing workspace An administrator opens Team → Users → your user → Groups → Add to Group
Your service account workspace_developers for API and SDK development An administrator opens Access → Service Accounts → your account → Groups → Add to Group
Workspace owner Signup assigns workspace_administrators Created during workspace setup; the owner's service account still needs its own membership

The built-in workspace_developers group grants access to build resources, including collections, records, functions, and triggers. It does not require making each developer a workspace administrator.

Missing Team or Access in the sidebar?

These management sections are visible to workspace administrators. Ask your administrator to assign your user and provision the service account in the following steps. You do not need administrator access just to run your application.

For a workspace with custom access rules, ask the administrator to confirm the group's permissions under Access → Permissions. The basic Quick Start needs collection creation and record creation, listing, retrieval, and updates. Collection authorization uses the structures resource; record authorization uses records. See Policies and Permissions for custom rules.

Step 3: Find or Create a Service Account

Service accounts authenticate backend applications, local scripts, and SDK calls using a client ID and client secret.

  1. Select the intended workspace in the console.
  2. Open Access → Service Accounts.
  3. If an administrator has already provisioned a development account for you, open it and confirm its name, client ID, and active status. Obtain its secret through your team's approved secret manager.
  4. Otherwise, choose New Service Account (or Create service account on an empty list), enter a descriptive name such as Local development, optionally add a description, and submit Create service account.
  5. Copy the client ID and client secret from the credentials dialog and save them securely. The secret is shown only once.

Service account creation form

An existing secret cannot be retrieved

If a secret is missing, ask the administrator whether to create a dedicated development account. Keys → Rotate Secret replaces the existing secret and invalidates it for other applications using that account. Coordinate rotation before using it on a shared account.

Assign the Service Account's Group

  1. Open the service account and select Groups.
  2. Choose Add to Group.
  3. Select workspace_developers, or the custom development group your administrator has configured.
  4. Confirm that the group appears in the membership list.

Service account Groups tab and Add to Group button

The screenshot illustrates the Groups tab on an administrator account. For this development flow, select workspace_developers; sidebar organization may differ.

Add the service account itself to the group. There is no need to add one group to another. workspace_administrators grants broad workspace administration access and is not the minimum development requirement. A token can be issued successfully even when the service account lacks permission to use a resource.

Step 4: Configure Local Credentials

Keep these values in your server environment or an ignored .env file:

CENTRALI_CLIENT_ID=sa_your_client_id
CENTRALI_CLIENT_SECRET=sk_your_client_secret
CENTRALI_WORKSPACE=your-workspace-slug

Variable name

The create-centrali-app templates and the Node.js and Next.js guides read this value from CENTRALI_WORKSPACE. The curl examples below use a shell variable named CENTRALI_WORKSPACE_SLUG. Both hold the same workspace slug, not the display name — it is the value the SDK expects for its workspaceId option.

Newly created service accounts use sa_ client IDs. Existing legacy IDs remain valid; always copy the exact ID shown for your account.

Add .env and .env.local to your project's .gitignore before saving credentials. Load the file with your framework's environment support or a library such as dotenv; a file alone does not export shell variables.

For the curl examples, set the values in your local shell:

export CENTRALI_CLIENT_ID="<your-client-id>"
export CENTRALI_CLIENT_SECRET="<your-client-secret>"
export CENTRALI_WORKSPACE_SLUG="<your-workspace-slug>"

Keep secrets out of source control, logs, screenshots, and browser code. Do not put a service account secret in a NEXT_PUBLIC_ or VITE_ variable. Browser applications should use the publishable-key or user authentication paths. Use separate service accounts for development and production.

Step 5: Verify Authentication and Resource Access

You need curl for these checks. First, exchange your credentials for a token:

curl --fail-with-body --silent --show-error \
  "https://auth.centrali.io/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$CENTRALI_CLIENT_ID" \
  --data-urlencode "client_secret=$CENTRALI_CLIENT_SECRET" \
  --data-urlencode "scope=openid"

A successful response contains access_token, token_type, and expires_in. Copy access_token into your shell without committing or sharing it:

export CENTRALI_ACCESS_TOKEN="<access_token-from-response>"

Then check that the service account can access collections in the same workspace:

curl --fail-with-body --silent --show-error \
  "https://api.centrali.io/data/workspace/$CENTRALI_WORKSPACE_SLUG/api/v1/collections" \
  -H "Authorization: Bearer $CENTRALI_ACCESS_TOKEN"

Expect HTTP 200 with the workspace's collection list, which may be empty. This verifies read access; the Quick Start exercises collection and record creation next. Obtaining a token alone does not verify permissions.

After changing group membership, request a new token and repeat the resource check. The SDK manages token acquisition and renewal for application code; see SDK Authentication.

Troubleshooting

Symptom What to check
No verification or invitation email Check spam and confirm the invited email address with the administrator. Follow the invitation flow when joining a team.
Team, Access, or service account creation is unavailable Ask a workspace administrator to provision the account and group membership.
Token request rejects the credentials Check the client ID and secret for whitespace, verify the account is active, and confirm the secret has not been rotated.
Token succeeds, but the resource request returns 403 Confirm the service account's Groups membership and the group's permissions. Your own user membership is separate. Check the workspace slug, then obtain a new token.
API returns 401 Check the bearer token and its expiry, then request a fresh token.
Collection list works, but creating data fails Ask the administrator to check create/update permissions for structures and records; read access alone is insufficient.

Next Steps