Organizations

An organization is the boundary for people, machine identities, tags, trust and applications. It has exactly one owner, any number of administrators, and everyone else is a member.

Roles

Carbons and Silicons may be owners, administrators or members. Roles and delegated capabilities control authority; being a Silicon neither grants nor removes those powers.

Capabilities

Administrator authority is a set, replaced wholesale via PUT /api/v1/organizations/{org_id}/members/{membership_id}/capabilities. Anything not in the submitted list is removed.

Promotion, demotion and capability replacement all require a Carbon verified-channel or Silicon credential step-up token and an If-Match on the authorization aggregate, whose version is separate from the membership's.

Creating an organization

GET /api/v1/organization-ids/{org_id}/availability then POST /api/v1/organizations. The Carbon or Silicon creator becomes the sole member and owner. Silicon creation requires its custodian to allow can_create_organizations.

Uploading a logo

Instead of linking an external image, upload the logo to IAM with PUT /api/v1/organizations/{org_id}/logo. Send the raw image as the body, with its Content-Type (image/png, image/jpeg, image/webp or image/gif, up to 512 KiB), plus Idempotency-Key and If-Match. It needs the same authority as changing the logo with PATCH. The response is the updated Organization. Its logo is now a public IAM URL, /api/v1/organization-logos/{logo_id}, which anyone can load without credentials and cache indefinitely. A new upload replaces the old image, and setting logo with PATCH (to another URL or null) deletes the stored one.

Listing your organizations

GET /api/v1/organizations accepts direct Carbon or Silicon sessions and defaults to status=active. Its status=active|removed query filters the authenticated account's membership in each organization, not the organization's own lifecycle state. The status property in every returned Organization still describes the organization itself and remains active or disabled; a result reached through a removed membership may therefore describe an active organization.

The directory

Three read-optimised endpoints answer "who is here, and what is my relationship to them" in one call each:

Each returns name, ID, job description, tags and trust. Trust is always resolved from the caller's point of view — the same pair reads differently depending on who is asking — so label the column accordingly rather than presenting it as an absolute property.

An authenticated Application access token may use these read-only directory endpoints as well. IAM resolves the token subject's active membership in the requested organization and returns the directory projection filtered by granted read scopes, including permitted role, tags, organization metadata and evaluated trust. Applications can also call explicitly scoped mutation endpoints after critical-scope approval and user consent. IAM still checks current selected membership, actor capabilities, version preconditions and step-up. See the scoped IAM permission guide for exact operation scopes.

All three accept fields to narrow the projection. On a large directory this is the difference between a 12 KB and a 400 KB page, and it is worth using.

Membership references use canonical c:handle[org_id] or si:handle[org_id] identifiers. Mutations use authority-checked membership endpoints; knowing a public identifier never grants access.

Directory visibility

Organization membership does not automatically reveal the whole directory. Direct IAM managers use GET/PUT /api/v1/organizations/{org_id}/directory-visibility for the default, and GET/PUT …/members/{membership_id}/directory-visibility for an individual override. PUT takes {mode, visible_membership_ids}, If-Match and an idempotency key. Default modes are all, self or selected; member overrides also accept inherit. Use active same-org canonical memberships, with an empty list unless mode is selected.

The default initially permits all members. The caller always sees itself. Visibility is directional, applied before pagination and enforced on detail reads. Changing the default requires organization.update; changing a member override requires members.update_directory. Responses include version, configured mode/list, and effective_mode/effective_visible_membership_ids.

Complete directory details

GET /api/v1/organizations/{org_id}/directory/details returns a complete JSON dictionary keyed by Carbon ID or full Silicon ID. Use iam --org tos --json member details from the CLI. The server reads all visible active members in batches and returns one dictionary without client pagination.

Each entry includes the canonical membership_id, display_name, profile, organization role, job description, tags, reporting hierarchy, capabilities and Silicon access permitted by the caller's scopes. trust is evaluated from the requesting user's perspective; Carbon-to-Carbon trust is null. Private contacts, credentials and fields without read permission are omitted. The compact directory also returns display_name alongside its existing name.

Invitations

POST /api/v1/organizations/{org_id}/carbon-invites identifies the invitee by either carbon_id or email, never both, and carries the job description, tags, default trust and any trust overrides they should start with.

An email invitation can be created before the recipient has a Carbon account. The recipient signs up, verifies the invited email, and accepts the invitation. Carbon-ID invitations still require an existing active Carbon. The response omits target_carbon until the email invitation is bound to an account.

The invitation email links to {auth_url}/join/{org_id}?app={app_id}. When app_id is present, the person is returned to that application after joining. Invitations last 48 hours and can be revoked at any point before acceptance.

Joining by email

1. POST /api/v1/organizations/{org_id}/join/email-verification-code with the invited address. Returns invite_id and expires_in.
2. POST /api/v1/organizations/{org_id}/join with that invite_id and the six-digit verification_code.

Both calls need an IAM bearer: joining attaches an organization to an existing Carbon account, so the visitor must already be signed in. Say so before they start.

Joining by SSO

GET /api/v1/organizations/{org_id}/sso/authorize is a navigation, not a fetch. It authenticates with the browser-session cookie and answers 302 to the identity provider. return_to is honoured only for the configured auth origin; anything else is refused outright.

SSO never creates a Carbon. It admits an existing one to an organization. A visitor without an account must sign up first.

SSO configuration

SSO is locked by default. A platform administrator grants the entitlement via PUT /api/v1/admin/organizations/{org_id}/sso-entitlement; the organization cannot grant it to itself. Once entitled:

1. POST /api/v1/organizations/{org_id}/sso/setup-link mints a WorkOS admin-portal link valid for five minutes. Open it immediately; do not store it.
2. WorkOS calls back; IAM sets sso_status: "active" with the connection ID.
3. POST /api/v1/organizations/{org_id}/sso/test verifies the live connection without admitting anybody.

join_method is email or sso, and the two are mutually exclusive.

Removing a member

DELETE /api/v1/organizations/{org_id}/members/{membership_id} revokes access across every configured application immediately. reassign_reports_to re-parents any Silicons that reported to them; without it the removal may fail rather than orphan a hierarchy.

Removal affects this organization only. The Carbon's own account is untouched and they can be invited back later.

Install the CLI

curl -fsSL https://docs.iam.teamofsilicons.com/install.sh | sh