# Identity and access profiles

> Every agent, person and application has an identifier no AI can change. Each agent has a signed, versioned access profile, and never exceeds the entitlements of the person it acts for.

Source: https://immiscible.fly.dev/docs/guides/identity-and-access

Governance is only as good as the names in it. If an agent could rename itself, change the person it acts for, or point a trusted tool at a new server, every rule above would be keyed to the wrong thing. This guide covers the identity layer underneath decisions.

## Identifiers no AI can change

The database itself refuses any update to an agent's id, workspace, principal or creation record, to an application's id or kind, and to a person's single sign-on link. Renames are allowed and recorded with the old and new names. Every ledger record carries a **subject**: the agent, person, single sign-on subject, application or key that acted.

## Applications

Every tool server, model provider and OAuth client an agent can reach is an **application** in the registry, with versions.

- **Repointing** a tool server to another origin, or swapping its credential, is a new version that a **second person confirms**: [`POST /api/w/:wid/applications/proposals/:pid/confirm`](https://immiscible.fly.dev/docs/api/post-api-w-wid-applications-proposals-pid-confirm.md).
- **Changed tools.** When a tool server's manifest changes, the new or changed tools are hidden from agents until an owner accepts the new manifest: [`POST /api/w/:wid/applications/:id/accept-manifest`](https://immiscible.fly.dev/docs/api/post-api-w-wid-applications-id-accept-manifest.md).
- **Retiring** an application removes it from every profile at once.

## The access profile

For each agent, Immiscible computes and signs one document saying everything it can reach: applications and tools, data fields, money, models and its tier.

```bash
curl "https://immiscible.fly.dev/api/w/$IMMISCIBLE_WORKSPACE/agents/agt_4f2c91a7/profile" \
  -H "cookie: __Host-sid=$IMMISCIBLE_SESSION"
```

The profile is versioned. Every decision records the profile version and hash it was made under, so "what could this agent do when it did that" has an exact answer. Compare versions with [`GET .../profile/diff?from=6&to=7`](https://immiscible.fly.dev/docs/api/get-api-w-wid-agents-aid-profile-diff.md), and check a signed profile someone sent you with [`POST .../profile/verify`](https://immiscible.fly.dev/docs/api/post-api-w-wid-agents-aid-profile-verify.md).

## Allowlists

Narrow an agent below what its mandates and the workspace would allow, per tool and per model:

```bash
curl -X PUT "https://immiscible.fly.dev/api/w/$IMMISCIBLE_WORKSPACE/agents/agt_4f2c91a7/allowlists" \
  -H "cookie: __Host-sid=$IMMISCIBLE_SESSION" -H "x-immiscible-csrf: 1" \
  -H "content-type: application/json" \
  -d '{ "tools": [{ "appId": "app_0c4d", "tools": ["list_issues", "create_pull_request"] }], "models": ["anthropic/claude-sonnet-5", "mistral/*"] }'
```

`tools` is a list of `{ appId, tools }` (tool names, or `["*"]`); `models` is a list of model ids, `provider/*` or `"*"`. Send `null` to clear either.

## Entitlements

A person's entitlements say what they may do: which tools, which models, which data fields and the largest payment (`tool`, `model`, `data_field`, `max_payment`). **An agent never exceeds the entitlements of the person it acts for**, whatever its mandates say. A member can read their own; owners and admins read and set everyone's.

Entitlements can also come from your identity provider's groups: map an SSO group to entitlements once with [`PUT /api/w/:wid/sso/group-entitlements`](https://immiscible.fly.dev/docs/api/put-api-w-wid-sso-group-entitlements.md) (owners only), and people pick them up when they sign in.

## Single sign-on

Immiscible signs people in with OpenID Connect: the authorisation code flow with PKCE, `state` and `nonce`, discovery from the issuer, and ID tokens verified locally against the provider's keys. It works with Microsoft Entra ID, Google Workspace, Okta and any standard provider.

1. An owner or admin opens **Settings**, then the **Single sign-on** tab, and enters the issuer, client id and secret, the email domains, and the default role for first sign-in (never owner).
2. Register the redirect URI shown there with the provider: `https://immiscible.fly.dev/sso/callback`.
3. Verify each email domain with the DNS TXT record the console shows. Until a domain is verified, nobody on it signs in through SSO and SSO cannot be enforced for it.
4. Optionally **enforce** SSO: password sign-in is then refused for every address on the verified domains. Owners with a passkey or an authenticator app keep a break-glass path, so a broken identity provider cannot lock you out. Step-by-step setup for Okta, Microsoft Entra and Google Workspace is in [Workspace single sign-on](https://immiscible.fly.dev/docs/guides/workspace-sso.md).

Later sign-ins use the provider's `(issuer, sub)` link only, so changing someone's email at the provider does not move them to another account. People removed in Immiscible stay removed.

For sign-in with Google, Microsoft and Okta accounts, passwordless email codes and passkeys, see [set up sign-in](https://immiscible.fly.dev/docs/guides/sign-in.md).

## Provisioning from your directory

People can follow your identity provider instead of being invited by hand. With [SCIM](https://immiscible.fly.dev/docs/guides/scim), Okta, Microsoft Entra or any SCIM 2.0 provider adds people, updates them and turns its groups into teams. Without SCIM, [directory sync](https://immiscible.fly.dev/docs/guides/directory) reads Google Workspace or Microsoft Entra every hour, after an owner has reviewed the first import.

Deactivating someone at the provider does what removing a member does, at once: their membership and governance roles go and every key they hold is revoked, agent keys included. Their console sessions end and their phones are signed out too, when the workspace owns their identity (a verified domain, a self-hosted deployment, or no other workspace). The last owner is never removed, and nobody is ever made an owner, by a directory.

## Two-factor

Password sign-in can require a TOTP code, with recovery codes. Owners and admins can require two-factor for the whole workspace under **Settings**, then the **Security** tab. People who sign in through SSO use their provider's own MFA.

## Recertification

Access does not last forever by default. A recertification campaign asks whoever answers for each agent to look at its profile as it stands and certify or revoke it; access not recertified by the due date is taken back. See [traces and reviews](https://immiscible.fly.dev/docs/guides/traces-and-reviews.md#recertification).