Overview

Silicon IAM is the identity and access layer for every Silicon application. It authenticates people and machines, holds the authoritative directory for each organization, and tells registered applications about changes they are permitted and subscribed to receive.

IAM is authoritative for membership. Removing someone invalidates their organization authority in subsequent IAM checks. Applications may cache scope-filtered projections, but must enforce revocations and verify current access for protected actions.

Three kinds of principal

Account IDs are independent of organization membership. A Silicon keeps the same si:head_of_growth ID when it joins another organization. Applications use globally unique bare IDs such as billing; bundle IDs retain their org>bundle namespace.

Identifiers, and what they are not

Carbon, Silicon, and Application IDs are immutable canonical identity keys, including in storage and foreign keys. They are never reused after deletion. Other resources retain UUID keys.

A public membership_id is carbon_id[org_id] or silicon_id[org_id], using the full Silicon ID: for example c:saket[tos] and si:helper[tos]. URL-encode the brackets in path segments. These stable identifiers also appear in relationship fields, trust selectors and webhook membership references. UUID membership keys remain private to storage. Identifier resolution never grants access; tenant, consent and resource authorization still apply.

Use the permanent carbon_id, full silicon_id, or app_id as the identity key. Generic actor objects expose the same identifier as public_id. There is no separate principal UUID.

How to read this documentation

openapi.yaml is normative. Where these pages and the specification disagree, the specification wins and the discrepancy is a bug worth reporting. What you get here is the reasoning: why an endpoint behaves the way it does, which failure modes matter, and what to do about each of them.

Read Authentication and Request conventions first. Between them they cover the rules that apply to every call in the contract, and almost every integration problem traces back to one of the two.

If you are integrating an Application in Rust, the official client provides typed API calls and models, explicit version negotiation, credential transports, and webhook verification. Your application still owns credential persistence, refresh coordination, OBO consent/token coordination, and retry decisions. These pages explain the contract behind those calls.

Environments

Timestamps are UTC RFC 3339. Request and response bodies are JSON unless an endpoint says otherwise; the OAuth token, introspection and revocation endpoints take application/x-www-form-urlencoded, as the OAuth specifications require.

Application authority in v1

For inter-app communication, an application can request a short-lived app_access_key using its own Basic credentials. A receiving application verifies the caller's ID and key using the receiver's own Basic credentials. This proves application identity; the receiver remains responsible for authorizing the action. The key grants no user permissions and does not replace OBO. See App verification.

Applications declare app_scope separately from their webhook_scope subscriptions. Critical permissions go through IAM or external-provider review. Users approve effective IAM permissions and choose organizations before IAM hands the application a short-lived token. OBO endpoints require separate on-demand approval and dedicated tokens. Apps never receive IAM credentials or verification codes.

External OBO can connect applications owned by different organizations while preserving the user's selected membership context. Bundles offer one displayed login identity for same-organization applications; tokens remain individually bound. Application testing environments reproduce the same contract with isolated credentials, recursively imported dependencies, fixed test OTPs, and configurable inactivity retention.

GET /api/v1/contracts describes the first official v1 contract and the current/deprecated/sunset lifecycle. Read Request conventions for negotiation and retirement rules.

Install the CLI

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