Users & Organization

Everything about who exists in your deployment — people, the org tree they sit in, the teams they collaborate in, and the service accounts that act on their behalf — is managed from Setup → People & Organization (/apps/setup).

The underlying identity objects (sys_user, sys_organization, sys_member, sys_business_unit, sys_team, sys_invitation, sys_api_key, …) live in your project database; see the identity layer table for what each one represents.

90% of daily administration is assigning people to positions. The positions, the permission sets behind them, and the security baseline ship with the platform and the apps you install. Your job is the people side — covered on this page — and the assignments, covered in Managing Access.

Build the organization (business units)

Setup → People & Organization → Business Units.

The business-unit tree is the one hierarchy in the access model: it decides visibility depth (unit, unit_and_below) and delegated-admin boundaries. Build it at onboarding, revisit it only on reorgs.

• The default Org Chart tab renders the tree as an indented expand-and-collapse tree grid.
• Create the root first (kind company), then add children with New, picking the Parent Business Unit in the form. The kinds division / department / office / cost_center are display hints — the tree works the same regardless.
• Reorganize by Edit-ing a unit and changing its parent. The tree view is a read-only presentation — re-parenting happens through the record form, not drag-and-drop.

Three similarly-named things, three different jobs — don't mix them up:

Keep the tree shallow and honest to your real structure. If something should affect what records people see by org structure, it's a business unit; if it's just a group people share records with, it's a team.

Add people

Setup → People & Organization → Users. Three ways in, all first-class:

Pending invitations are listed under Setup → People & Organization → Invitations.

People cannot create their own accounts unless you open self-registration: since ObjectStack 17.3 the sign-up audience defaults to invitation only, and these three paths are how people arrive. They work whatever the audience is set to. To let people sign themselves up, see Authentication → Who may sign up.

The same flows exist over REST (ObjectStack 14.3+) for scripted onboarding:

# Create a sign-in-ready account with an optional one-time password
curl -X POST https://crm.example.com/api/v1/auth/admin/create-user

# Bulk-import rows / CSV / XLSX (max 500 rows), with dry-run and upsert modes
curl -X POST https://crm.example.com/api/v1/auth/admin/import-users

Since 16.0 the import default is passwordPolicy: 'auto': rows with a deliverable channel (a real email plus a wired email service, or a phone number with the SMS invite path) are invited; only unreachable rows get a temporary password (returned once, must_change_password). Pass passwordPolicy: 'none' explicitly for the old identity-only behavior; per-row outcomes surface on rows[].delivery, with a summary.delivery breakdown.

Payloads, password policies, and phone-only accounts are covered in Authentication → Admin user management.

Organization-membership tiers

Every membership row (sys_member) carries a tier — the standing a user holds in the organization. The vocabulary is closed and owned by the platform (ADR-0108): these four values, and nothing an app declares widens them.

Two different records are called a "membership" on this page. sys_member answers which organization do you belong to, and at what tier. sys_business_unit_member — the next section — answers which business unit do you sit in. Placing someone in the org tree changes no tier, and changing a tier places nobody.

The tier is chosen on the invitation (sys_invitation.role) and stored on the membership row (sys_member.role). Both fields are the same fixed four-value select, so an application's own business role (sales_manager) cannot be stored in either, and an invitation naming one is rejected before any row is written. Job function is a position.

Two rules bound who may hand out which tier: an invitation may never confer a tier above the issuer's own, and an issuer below admin may invite only as member.

A tier is a grade that decides what you can reach — never a bundle of what you may do. The visible power of owner and admin comes from a separate mechanism: memberships at those two tiers are automatically granted an organization-admin permission set scoped to that organization. That permission set carries the authority; the tier only decides who receives it.

delegated_admin is not delegated administration

Two mechanisms with near-identical names. Reaching for the wrong one is the mistake this section exists to prevent:

The two are doubly opt-in and independent: someone must set the membership tier and grant an adminScope before a scoped delegate can issue an invitation that also places the new person in a business unit with positions. Granting one is not granting the other — holding delegated_admin confers none of the powers listed under delegated administration.

Place people in the org tree (memberships)

Placing a person in the org tree is a separate record: a Business Unit Member row (sys_business_unit_member — user + business unit, one marked primary). Depth-based visibility and unit_and_subordinates sharing resolve through this membership, so don't skip it — a user without a membership row is invisible to depth-based rules.

When someone changes departments, update their Business Unit Member row and re-anchor their position assignments — see Managing Access.

Teams

Setup → People & Organization → Teams. Teams are flat collaboration groups: sharing rules and record shares can target them, but they never carry permission sets. Use them when a cross-department group needs to see a set of records without changing anyone's job function or the org tree.

User lifecycle

Day-to-day lifecycle actions live on each user's row menu and record header:

To deactivate someone, Ban them first — sign-in is blocked immediately — then remove their position assignments and memberships at leisure. The full offboarding sequence is in Managing Access.

Users' own self-service password recovery depends on a configured email or SMS delivery service. Until one is wired up, admin Set Password (temporary, must-change) is the reliable fallback.

Service accounts & API keys

Integrations and headless agents authenticate with an API key (sys_api_key) — a long-lived programmatic credential bound to a user. Every call made with the key runs as that user, with that user's permissions.

For anything beyond personal scripting, create a dedicated service user:

1. Create User for the integration (no invite needed).
2. Assign it the smallest permission set that covers the integration's objects — never an admin set.
3. Mint an API key for it, from Setup → Connect an Agent or over REST:

curl -b cookies.txt -X POST https://crm.example.com/api/v1/keys
# → { "key": "osk_..." }  — shown once; store it in your secret manager

Key usage, headers, and rotation are covered in API Access; connecting AI agents with a key is covered in Connect AI Tools (MCP).

FAQ

A new user sees almost nothing — broken? No: that's the baseline working. Every authenticated user gets the additive member_default baseline; real access arrives when you assign a position.

Department vs. team? Department = business unit (hierarchy, visibility). Team = flat sharing group.

Can I delete the built-in permission sets? No — sets like member_default and organization_admin are the platform baseline. Shipped sets can be overlaid or simply left unassigned.

Where to go next