Organizations & workspaces

Caltra uses a small resource hierarchy to keep ownership and runtime data scoped correctly.

Organizations

An organization is the top-level administrative boundary. Platform users receive organization-scoped access through its memberships; the organization also owns environments, workspaces, and their runtime resources.

Create an organization from the operator app after signing in as a platform user. The creator becomes its owner. Organization names must contain between 2 and 80 characters, and owners or administrators can update the name from organization settings.

Environments

An environment separates deployment contexts inside an organization. For example, a team may use distinct environments for production and pre-production workloads.

Environment provisioning is coordinated with the Caltra team during early access. The dashboard reports the environments available to the selected organization.

Workspaces

A workspace belongs to exactly one environment and organization. It is the boundary used for tenant users and runtime resources, which prevents one product surface from reading another surface’s identities or agent state.

For a customer application, use one workspace per customer organization. The Caltra server SDK maps your stable organization ID to a workspace owned by the Caltra organization associated with your API key. No separate Caltra application ID is required:

const workspace = await caltra.workspaces.get({
  externalId: organization.id,
  createIfMissing: { name: organization.name },
});

Call this after your organization transaction commits. Repeating it is safe, including from a retry or concurrent request: the same external ID resolves to the same workspace. Omit createIfMissing for a lookup-only call that returns null when the mapping is absent.

Once available, choose a workspace on the Tenant users page to inspect or add its end-user identities.

Choose boundaries deliberately

Use a new organization when administrative ownership or billing must be independent. Use a new environment when deployment policy must differ. Use a new workspace when agent data and tenant identities need an isolation boundary within the same deployment context.