# Administer a workspace

What an owner or an admin sets up for a workspace: who signs in and how, who may do what, how long data is kept, where alerts go and how strictly the gateway governs.

## Single sign-on

An owner connects the workspace to the company’s identity provider in **Settings › Access › Enterprise SSO**. OIDC is included from the Growth plan; SAML 2.0, for identity providers that only speak it, with Enterprise.

- Only an owner saves the identity provider, switches SSO-only mode on or off, or removes it: the identity provider decides who signs in as any address of the domain. Each change is audited before it is written.
- Prove that you own the e-mail domain: add the TXT record the screen shows to its DNS, then press **Verify the domain**. Nothing is routed to your identity provider before; a DNS change can take up to an hour to show.
- Test **Continue with company SSO** on the sign-in page, then switch SSO-only mode on: password, Google and e-mail-link sign-in are then off for every address of the domain.
- Saving another identity provider — another issuer or client ID, another SAML entity ID or signing certificate, another protocol — withdraws the domain’s proof and switches SSO-only mode off: verify the domain again. Saving the same provider, with a new client secret or the same metadata, keeps both.
- Signing in through SSO grants no membership: people join a workspace by invitation, or through SCIM.

### SAML 2.0

- The SAML setup box gives the entity ID and the ACS URL to register at your identity provider. Give Azoth the provider’s metadata: its URL, or its XML pasted — an identity provider on your own network is configured with its XML. Once the provider is saved, `/api/sso/metadata?workspaceId=<id>` serves the service provider’s metadata, which most identity providers import in one step.
- The Name ID must be persistent and stay the same for a person: a new Name ID is a new account.
- Logout started at the identity provider is honoured: register `/api/sso/logout` on your Azoth address as the logout URL. A signed logout request, in the HTTP-Redirect or the HTTP-POST binding, ends every Azoth session of the person it names. Requests signed with SHA-1 are refused: sign with SHA-256 or stronger. In Azoth’s cloud, the answer sent back to the identity provider is not signed.
- When the identity provider’s signing certificate changes, save its new metadata in the same screen.

### OIDC

- Enter the domain, the issuer URL, the client ID and the client secret, and register at your identity provider the redirect URI the screen shows, with the scopes `openid email profile`. Azoth reads the discovery document before saving. The client secret is stored encrypted and never shown again: leave the field blank to keep it.
- Azoth runs the sign-in itself and checks it before any session exists: an issuer that belongs to one organisation, the ID token’s signature (RS256, PS256 or ES256) and claims, and an e-mail address of exactly the verified domain, which your identity provider says it verified.
- Microsoft Entra ID: a single-tenant issuer (`https://login.microsoftonline.com/<tenant-id>/v2.0`, never `common`, `organizations` or `consumers`) and the optional claim `xms_edov` in the ID token. Google Workspace: an OAuth client internal to your Workspace, so that Google sends the domain (`hd`).
- OIDC has no single logout: a session ends when it expires — by default eight hours after the person signed in.

## SCIM provisioning

SCIM 2.0 lets your identity provider — Microsoft Entra ID, Okta, PingOne, JumpCloud and others — add and remove the workspace’s members. Open **SCIM user provisioning** from Settings › Access › Enterprise SSO. SCIM is included with the Enterprise plan, as SAML is: on another plan no token is created, and the identity provider’s calls are refused.

- Tenant URL: `https://www.azothos.ai/api/scim/v2`, or your own host when self-hosted. The workspace is the token’s, never the URL’s.
- An owner or admin creates the bearer token the identity provider sends. It is shown once, stored only as a keyed hash, and revoked from the same screen: the identity provider’s next call is then refused.
- Users are created, read, updated (PATCH, `active` included) and deleted; a list filters on `userName eq` and `externalId eq`. Map `userName` to the person’s e-mail address and `externalId` to their stable directory id. There are no bulk operations.
- A person provisioned this way joins as a member. Their role comes from their groups, below: turn on group provisioning at your identity provider.
- Deprovisioning — `active` set to false, or the user deleted — removes the membership at once: the mandates the person answered for are suspended, and their personal keys revoked. An account this workspace’s SCIM created and nothing else holds is disabled, never deleted. The workspace’s owner cannot be deprovisioned through SCIM: transfer ownership in Azoth first.

A group gives a role only under one of these display names — case, surrounding spaces and the separators `_` or `-` aside:

- `Azoth Owners` — Admin — SCIM never grants the owner role
- `Azoth Admins` — Admin
- `Azoth Finance` — Finance
- `Azoth Security Officers` — Security officer
- `Azoth Analysts` — Analyst
- `Azoth Members` — Member

- Any other name gives no role: a team’s group such as Finance team grants nothing. Your identity provider can name the role instead, with the attribute `urn:ietf:params:scim:schemas:azoth:2.0:Group:mappedRole`, which always wins.
- A person in several groups gets the most privileged of their roles: admin, then security officer and finance — security officer wins between those two — then analyst, then member. Removed from the last group that gives them a role, they leave the workspace.
- A group whose name gives no role never lowers or removes anyone’s role. Each role a group grants or takes away is audited before it applies.

## Roles

Each member holds one role in a workspace. **Settings › Access › Team** invites and changes members as owner, admin, member or analyst; the finance and security officer roles come from SCIM groups.

- **Owner** — Everything an admin does, plus the payment method, single sign-on, the requirement of two-factor authentication, which actions need four eyes, litigation holds and deleting the workspace. A workspace always keeps an owner, and only an owner grants the owner role.
- **Admin** — Configures the workspace, manages members, roles and API keys, decides approvals. Cannot delete the workspace, change the payment method or the identity provider.
- **Finance** — Billing — invoices and the payment method — and usage, with the audit log read-only. No configuration and no members.
- **Security officer** — The audit log, its export and its forwarding to your SIEM; reads the single sign-on settings, the API keys and the alert routes. No billing, no members, no model calls.
- **Member** — Calls models through Azoth and sees their own usage; reads the rules and the settings.
- **Analyst** — Read-only: usage and the audit log, no model calls.

> An invitation with a role above member grants that role: when role changes need four eyes, it waits for a second owner or admin, and nothing is sent before. So does the removal of an owner or an admin: they keep their access until it is approved. Every role change is audited before it applies.

## Four eyes

Some acts take effect only once a second person approves them. The person who asks never approves their own request: Azoth checks it, and the database checks it again.

- An owner chooses, in **Rules › More › Approvals**, which of these need a second owner or admin: changing a member’s role, publishing or changing a live rule, changing data retention. Approving a connector can need four eyes too; only an owner approves one, so the second person is another owner.
- These always need one: running a call a rule holds for approval, an agent action or an MCP tool call that needs a person, an answer the grounding check held, a red-team waiver, a reading of the law (a rule applied otherwise, a zone that prevails), releasing a litigation hold.
- A request waits in **Rules › More › Approvals** and on the home page, and expires after 72 hours. Approved, the act runs with the approver as the one acting; each decision is audited and sealed.
- When the setting cannot be read, the act waits for a second person rather than run on one. A request made with an API key whose person is unknown can be rejected, never approved: four eyes needs to know who asked.
- Four eyes needs a second owner or admin — a second owner for a connector’s approval: invite one before you turn it on. An exception to a rule is decided by the rule’s owner or an owner or admin, never by who asked it ([exceptions](https://www.azothos.ai/docs/rules#exceptions)).
- From Slack or Teams, owners and admins linked with MFA decide held calls, agent and MCP actions, held answers and rule publications; owners linked with MFA also decide connectors. A role change, a retention change, a red-team waiver, a reading of the law and a hold release always open in Azoth.

## Access reviews

An owner or admin reviews who holds which rights in **Settings › Access › Access review**.

- The review lists the members with their role, last sign-in, two-factor authentication and sign-in method; the pending invitations; the API keys with their role, scopes, expiry and last use; the SCIM tokens; whether two-factor authentication is required; and which actions need four eyes.
- It points out what to look at: an owner or admin without two-factor authentication, no sign-in for 90 days, an API key without expiry, unused for 90 days, on the old hashing or with no scope restriction.
- Download it as JSON, or the members as CSV, correct what should not be there, then mark it done. Preparing it and marking it done are sealed in the workspace’s journal — its fingerprint and counts, never the e-mail addresses. Run one every quarter.
- What Azoth’s own staff do on your workspace is sealed in its journal too (`staff_access`). In Azoth’s cloud they reach its data only through a support access an owner agreed to, for 4 hours at most.

## Retention

An owner or admin sets how long the workspace keeps each kind of record in **Settings › Modules and retention › Data retention**:

- **Usage traces** — 30 to 365 days
- **Routing decisions** — 30 to 365 days
- **Loop events** — 7 to 180 days
- **Reused responses (cache)** — 7 to 90 days
- **Audit logs** — 365 to 730 days

- The nightly purge applies these windows and the data policy’s own retention: the shortest wins. When retention changes need four eyes, a change waits for a second owner or admin — a data policy that keeps traces for less time too. A new data policy that sets no retention keeps the window in force. A reused response is served 7 days at most and deleted once it expires, whatever its window.
- The law that applies to you can set a floor: the screen shows it and refuses a shorter window, and the purge never goes below it.
- The sealed decision journal is kept as long as your plan or your contract says, and never less than that floor. Once applied, its oldest entries are removed each night behind a sealed checkpoint, so the chain stays verifiable from where it starts; the screen says whether this is applied yet.
- A litigation hold keeps what it designates whatever the windows. An owner places it on chosen decisions; while it is active the purge keeps their traces, an erasure keeps their envelope, and the workspace can be neither deleted nor erased with its owner (`legal_hold_active`). Releasing it takes four eyes ([litigation holds](https://www.azothos.ai/docs/dossiers#hold)).

## Alert routes

Every alert of the workspace goes to the routes of **Settings › Integrations and alerts › Alerts**, the one place an alert’s destination is set.

- A route names a channel — PagerDuty, a Slack or Teams channel webhook, or an e-mail address — and a minimum severity (`info`, `low`, `medium`, `high` or `critical`): it receives the alerts of that severity and above. A delay sends them only after it, to page on-call only when nobody acted.
- The alerts: approvals and exceptions waiting for a decision; governance alerts (refused calls, residency, proof gaps, unmandated uses); sign-in anomalies (repeated failures, rapid role changes); provider outages; model version changes and regressions; agent loops Azoth stopped; the sealed-decision quota nearing or reaching its limit.
- Owners and admins change the routes, and send a test to a Slack or PagerDuty route; security officers see them.
- Budget thresholds go to the destinations set with each budget. Governance events can also be pushed to your own endpoints ([governance webhooks](https://www.azothos.ai/docs/webhooks#governance)).
- Name a security contact in **Settings › Organization**: beside the owners and admins, they are told of a personal-data breach of the workspace’s data.

## Two-factor authentication

Each person turns on two-factor authentication with an authenticator app (TOTP) in **Settings › Access**; from then on, every sign-in asks for its 6-digit code.

- An owner can require it of every member of the workspace. The owner’s own session must have passed it first, so that nobody locks the workspace out; then a member without it is refused (`mfa_required_by_workspace`) until they turn it on and sign in again. The access review shows whether it is required.
- Deciding an approval from Slack or Teams needs an account linked with MFA.
- Azoth’s own staff always use it: a platform administration screen refuses a session without it.
- An API key does not sign in, so two-factor authentication does not apply to it: give keys scopes and an expiry, and review them.

## Governance mode

An owner or admin chooses how strictly the gateway governs the workspace in **Settings › Organization › Governance mode**:

- **Observe** — Calls without an approved mandate are served and flagged in the journal: nothing new is blocked.
- **Govern** — The same, plus an alert to the admins for each such call.
- **Enforce** — Calls without an approved mandate are blocked, and each block is sealed.

- The mode decides what happens to calls not tied to an approved mandate, to mandates nobody answers for any more or that ended, and to the applicable law. Rules, budgets, the emergency stop and prohibited practices (EU AI Act art. 5) block calls in every mode.
- The mode that applies is the stricter of the deployment’s and the workspace’s: a workspace can only tighten it, never loosen it. The screen greys out the modes looser than the deployment’s.
- Each change is audited before it is written, then sealed. Every decision seals the mode it was taken in, so a dossier shows whether Azoth was observing or enforcing.
- If the workspace’s choice cannot be read, nothing loosens: the last value read is kept for up to 10 minutes, then the call is governed in Enforce.
- A system classified as prohibited is refused in every mode, whatever its status: no mode, exception or waiver serves it.
- Before choosing Enforce, check **Mandates › Systems and agents**: every call not tied to an approved mandate is then refused.
- Agents have their own posture, in **Settings › Access › Agent Guard posture**: Observe checks each tool call against its mandate and seals it; Enforce blocks the calls outside the mandate and holds irreversible actions for a person. It too can only be stricter than the deployment’s.

## Human attribution

A decision can name the person a call was made for — sealed as a pseudonym, never a name — so that a dossier can say who launched it. It is set up in **Settings › Access › Who made each call**.

- **Personal key** — Every call is its owner’s: the owner or admin who created it, for themselves. It can never name anyone else, and it is revoked when its owner leaves the workspace or is erased.
- **Service key that may name the person** — Allowed when the key is created. The application sends `X-Azoth-On-Behalf-Of` with the person’s SCIM id or e-mail address, and the call is attributed to that member.
- **Service key** — Names nobody, as before.

- A key’s kind is fixed when it is created: to change it, create another key.
- The identifier the application sends is matched to a member, then dropped: never stored, logged or sealed. The decision seals a pseudonym of the member — a different one in each workspace — and how the person was known. Erasing the person deletes the pseudonym’s link, and the chain still verifies.
- A header that names no member is served and recorded as unresolved. `X-Azoth-End-User` is something else: the anonymous visitor of a public system.
- An owner or admin can turn on **Require every call to name its person**: a call that names no member is then refused, and the refusal is sealed. The change is audited and sealed.
- The refusals: `on_behalf_of_not_allowed` (403: a key that may not name people sent the header), `human_identity_required` (400: the workspace requires a person and the call names none), `identity_unavailable` (503: the key or the requirement could not be read, and the call is refused rather than served unchecked), `invalid_on_behalf_of` (400: a malformed header). Each is explained in [Error codes](https://www.azothos.ai/docs/errors).
- On a deployment in its default setting, until a workspace uses attribution — a personal key, a key allowed to name people, or the requirement on — its calls are served exactly as before, and the `X-Azoth-On-Behalf-Of` it sends is ignored.
