Silicon IAM HTTP API

The first official contract is v1 at https://backend.iam.teamofsilicons.com/api/v1. OpenAPI specifies the wire format. Read the hosted guide at docs.iam.teamofsilicons.com/api.

Authentication and request rules

Negotiate with unversioned GET /api/version and Silicon-IAM-Supported-API-Versions: v1, then verify the selected major and response header. GET /api/v1/contracts lists contract status and activity. Breaking changes receive a new major. A deprecated contract becomes eligible for sunset only after at least seven days without requests, with a conservative one-minute allowance for coalesced activity timestamps. Current v1 does not sunset merely because it is idle.

Use direct IAM Carbon or Silicon bearers for IAM account and organization actions. Confidential applications use Basic credentials for token exchange, introspection, revocation, discovery, app verification, OBO, and application testing setup. Their OAuth bearers can read only resources covered by current approved scopes, user consent, and the selected active membership. They cannot approve their own additional permissions or enter first-party management flows.

Mutation endpoints require an Idempotency-Key where documented; resource updates also require the documented strong If-Match version. Reuse the same key and payload for an uncertain retry. OBO verification accepts no idempotency key and does not consume the reusable access token. App verification key issuance creates an independent key on every request and has no idempotent replay. OAuth form endpoints use application/x-www-form-urlencoded; other endpoints use their declared JSON content type. See conventions, authentication, and errors.

Example: external application login

Register briefcase with declared app_scope permissions. Send the user to:

https://auth.iam.teamofsilicons.com/login?app_id=briefcase&redirect_uri=https%3A%2F%2Fbriefcase.example%2Fauth%2Fcallback%3Fstate%3DBROWSER_STATE

IAM authenticates the user, presents the app and current permissions, obtains consent, and asks which organizations to share. The application supplies no organization selector in the login URL. IAM returns to the callback with slt; the application's server exchanges it using its own Basic credentials:

POST /api/v1/app-auth/tokens
Authorization: Basic <base64(briefcase:app_secret)>
Idempotency-Key: <one logical exchange>
Content-Type: application/x-www-form-urlencoded

app_id=briefcase&slt=<URL-encoded-SLT>

The SLT lasts two minutes and can be exchanged once. The response contains an application access token and a rotating refresh token. Bind the callback to the browser's initiated login and remove its credentials from the URL. Applications never receive IAM credentials, IAM session tokens, passwords, or OTPs.

A direct IAM client first gets /app-auth/organizations?app_id=..., then submits the exact returned scope_version and complete approved_scopes together with explicit org_ids to /app-auth/short-lived-tokens. Changed scope versions require fresh consent. Only selected organizations are accessible; future memberships are not added automatically. Consent guide.

Permissions, review, and discovery

app_scope.iam selects named IAM permissions. app_scope.external selects {app_id, endpoint_id} from published external applications. Basic identity and profile are defaults. webhook_scope separately selects event categories; it never grants data access.

The scope catalog describes each permission and whether it is critical. Initial critical access waits for review; an existing application uses its prior effective permissions while additions are reviewed. Scope request threads support explanations, reviewer instructions, replies, approvals, and denial reasons with email notifications. Approval and user consent are separate requirements. Applications guide.

Verified apps can discover another verified app's base_url and published OBO endpoints across organizations. The originating login binds one membership, independently of either app's owner. Consent can select a different account and organization per provider. An OBO authorization request selects one of those memberships and named endpoints. Separate user approval creates endpoint grants; the app redeems the authorization code for dedicated access/refresh token pairs. The recipient verifies the reusable access token on every request. OBO guide.

Verify an application's identity

App A authenticates with its own HTTP Basic app credentials and sends POST /api/v1/app-verification/keys with JSON {} for the default five-minute lifetime, or {"ttl_seconds":600} to request ten minutes. The inclusive range is 60–3600 seconds. IAM returns {app_access_key, valid_till, app_id} and stores only the key's hash. Multiple keys can remain valid concurrently.

App A presents its ID and key to App B. App B authenticates to IAM with App B's own credentials and posts App A's {app_id, app_access_key} to /api/v1/app-verification/verify. A valid key returns {valid_key:true, valid_till, app_id}. An unknown, expired, revoked or mismatched key returns only {valid_key:false}. Invalid receiver credentials return 401. Verification does not consume the key. The receiver still authorizes the action; this key provides application identity without user permissions or OBO authority.

These routes use the main IAM backend. Accepted app-secret rotation revokes keys issued under the previous secret, and disabling an app revokes its outstanding keys. Testing keys require the same environment and current cleaning generation and never verify in production. Keep keys out of logs and ordinary application reads. See the complete flow.

Batch and bundle login

/login?app_ids=... validates up to 100 apps, collects each app's permissions and organization choices, and atomically creates app-bound SLTs. A bundle groups same-organization applications behind one displayed identity and one organization picker, using /login?bundle_id=.... Both callbacks return individual SLTs in a URL-encoded JSON #slts= fragment. Every app exchanges its own SLT using its own secret. Bundles have no secret and no nested membership. Batch login, bundles.

Current authorization and webhooks

Basic-authenticated introspection checks opaque application tokens online and returns scope-filtered authorization snapshots for selected organizations. Applications can bootstrap their cache without waiting for a directory event. Webhooks deliver authorized before/after changes at least once, filtered by effective scopes, user consent, and event subscriptions. Invitation, governance, and tag-definition events require their exact organization permissions. Own-profile access covers display name, photo, and timezone; own-trust access covers only effective trust from the user’s perspective. Raw SSO and Silicon credential/webhook management configuration are excluded from application deliveries. Silicon subscriptions retain their separate event vocabulary. Verify raw-body signatures, deduplicate event IDs, and apply resource versions in order. Webhooks guide.

Email invitations before signup

An organization can invite an email address before its recipient has a Carbon account. Creation stores the invitation without creating an account or granting membership. The recipient follows /join/{org_id}, signs up or signs in, then verifies that exact invited email before accepting. IAM binds the invitation only to the current active Carbon with that verified contact. Invitations last 48 hours and may be revoked before signup.

target_carbon is absent until the invitation is bound; clients can display masked_delivery_address while signup is pending. Carbon-ID invitations still require an existing account. Email invitation guide.

Testing environments

An application can create a testing environment with its production Basic credentials or attach to an existing iam_test_key. IAM imports its declared external dependencies recursively, producing isolated test app credentials in one environment. Receiving applications authenticate any supplied test app secret against IAM before entering their own isolated storage. All subsequent API operations use the environment key and credentials issued there. Test OTPs are 000000, and no real email or SMS is sent.

Imported production webhook secrets are never revealed. Test deliveries use a signed test envelope. Changing an imported webhook destination can generate a fresh test-only signing secret. Individual application inactivity retention defaults to 30 days and is configurable through testing_idle_days. Testing guide.

Endpoint guides

Install the CLI

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