---
title: "Security and Access Control"
group: "Reference"
groupOrder: 5
order: 3
---
STAIR secures agents with SSO sign-in, roles, per-record ACLs, managed secrets, PII masking and an Activity Log of every change.

## How security and access control work in STAIR

Every request to STAIR passes the same checks, in this order:

1. **Identity.** A person signs in through SSO. A script or integration sends an `aip_sk_` API key, which acts as the user or the service account that owns it.
2. **Role.** The role decides which kinds of objects you may see and create, for example whether the **Models** or **Service Accounts** pages are available.
3. **ACL.** The record's Access Control List decides what you may do with one specific agent, toolset, model, secret or other record.
4. **Data protection.** For agents that handle personal data, STAIR masks PII before anything reaches the LLM provider.
5. **Audit.** Every create, update, status change, delete and ACL change is recorded in the **Activity Log**.

## Sign-in with SSO

The STAIR Console, STAIR Chat and Knowledge share one single sign-on (SSO) login page, provided by Keycloak. Signing in to one app signs you in to the others. Users and teams come from the identity provider: teams are synchronized on a schedule set in **Administration** → **Automation** (**Keycloak sync**).

Your display name and role are shown at the bottom of the sidebar. **Logout** in the user menu ends the session.

**Identity Providers** under **Administration** are a separate feature: they configure OAuth for toolsets that call MCP servers on the user's behalf, not the sign-in to STAIR. See [Toolsets and MCP Tools](/docs/toolsets-and-mcp-tools/llm.md).

## STAIR roles

Each user has one or more roles. The role label (Root, Admin, User or Classifier) appears under the user's name in the sidebar.

| Role | What it allows |
|---|---|
| **Root** | Full access to everything, regardless of ACLs. Root also adds custom MCP catalog entries. |
| **Admin** | Manages shared infrastructure: models and model providers, toolsets, skills, MCP Catalog, registries, server instances and MCP Gateways, secrets, service accounts, schedules and **Administration**. Also has everything a User has. |
| **User** | Creates and uses agents, workflows and agent evaluations, works in STAIR Chat, and creates personal API keys. Sees records shared with them through ACLs. |
| **Classifier** | Manages **Classifications** and assigns them to agents, toolsets, skills, workflows and MCP Gateways. Can view all records so that they can be classified. |

Roles are assigned in the identity provider, not in STAIR. Service accounts have no role from this list: they can only use the records they were granted in ACLs. See [API Keys and Service Accounts](/docs/api-keys-and-service-accounts/llm.md).

## Owner and ACL permissions

Agents, toolsets, skills, workflows, agent evaluations, models, secrets, server instances, MCP Gateways, schedules and service accounts each carry their own ACL. You edit it on the record's **Access Control** tab (or the **Access Control List** section of a dialog).

| Setting | Meaning |
|---|---|
| **Owner** | The primary maintainer or team accountable for the record. Required where shown; defaults to you. |
| **Read Access** | Can view the record. |
| **Write Access** | Can edit the record. |
| **Manage Access** | Can edit the record, change its ACL, and delete it. Required; defaults to you. |
| **Execute Access** | Can run or call the record: chat with or call an agent, call a model, run an agent evaluation, or connect to an MCP Gateway. |

Permissions include the weaker ones: **Manage Access** includes write, execute and read; **Write Access** includes execute and read; **Execute Access** includes read.

ACL entries can name a user, a team or, for **Execute Access**, a service account. Granting a team gives the permission to all its members. Pickers search users by name, email or team.

To let an integration call an agent, add its service account to the agent's **Execute Access**. To let a colleague change an agent but not delete it or change who can see it, give them **Write Access**.

## How to review permissions in ACL Rules

**ACL Rules** shows, for one user, team or service account, every record they can access and with which permissions. It is a read-only view: change permissions on each record.

1. In the sidebar, open **ACL Rules**.
2. Search by name, email or description, and optionally narrow the list with **All**, **Users**, **Teams** or **Service Accounts**.
3. Select the principal. For a user, the card shows their **Roles** and **Teams**.
4. Review the **ACL** section. Records are grouped by type (Agents, Toolsets, Skills, Models, Secrets, Server Instances, Workflows, Service Accounts), with the columns **Name & Description**, **Owner**, **Read**, **Write**, **Manage** and **Execute**.
5. Use **Filter records** to find one record, and choose **All sources**, **Direct only** or **Via teams** to see whether a permission was granted to the person directly or through a team.

![ACL Rules filtered to Demo, with the service account Demo · Helpdesk Portal selected and its Execute permission on the agent Demo · Support Triage.](./security-and-access-control-acl-rules-service-account.png)

## How secrets are handled in STAIR

LLM provider API keys are stored as **Secrets** and referenced by name from the model provider. Static toolset header values and MCP server instance environment variables are entered in the toolset or the instance itself.

- **Secrets** (sidebar group **Configuration**) is available to Admins. The list shows each secret's value masked.
- **Show Value** reveals a value only to users the secret's ACL allows. Each secret has its own **Read Access**, **Write Access** and **Manage Access**.
- Credentials that belong to one person stay with that person. When a toolset asks each user for a token or an OAuth sign-in, STAIR stores it per user. Each user sees and revokes their own credentials in the user menu under **Connections** → **Toolset**, and toolset owners see who is connected on the toolset's **Connected users** tab.
- API keys are stored only as a hash, so they can never be displayed again after creation.

See [Secrets](/docs/secrets/llm.md).

## How PII masking protects personal data

PII masking is set per agent, in the **Personally Identifiable Information** section of the agent's **General** tab.

1. Open the agent in edit mode.
2. Turn on **Handles personal data**.
3. Select at least one entry in **PII Entity Types**.
4. Click **Update**.

![The Personally Identifiable Information section of the agent Demo · Support Triage, with Handles personal data set to Yes and four PII entity types.](./security-and-access-control-agent-pii-section.png)

When the switch is on, STAIR detects the selected entity types in every message and replaces them with typed placeholders such as `<PERSON_1>` or `<EMAIL_ADDRESS_1>` before the text reaches the LLM provider. The LLM only ever sees the placeholders. Tools that the agent calls receive the real values, and the user sees the real values in the answer.

| Entity type | Label in the agent form |
|---|---|
| `PERSON` | Person name |
| `EMAIL_ADDRESS` | Email address |
| `PHONE_NUMBER` | Phone number |
| `LOCATION` | Location |
| `CREDIT_CARD` | Credit card number |
| `IBAN_CODE` | IBAN |
| `IP_ADDRESS` | IP address |
| `RU_PASSPORT` | Russian passport number (Russian only) |

Detection works for English (`en`) and Russian (`ru`) text.

PII masking is **fail-closed**: if the PII detector is unavailable, the request fails instead of sending unmasked data to the LLM.

## How to audit changes in the Activity Log

The **Activity Log** records every change to STAIR records: who changed what and when.

1. In the sidebar, open **Activity Log**.
2. Search by **Name** or **User** (the field selector next to the search box).
3. Narrow the list with **Type** (for example Agent, Toolset, Model, Secret, Service Account, Key, MCP Gateway, Workflow) and **Operation** (**Created**, **Updated**, **Status Changed**, **Deleted**, **ACL Updated**). **Clear Filters** resets them.
4. Click the arrow at the start of a row (**Show details**) to see the **Changes** for that entry, with added and removed lines.
5. Use **Open** to preview the record, **Refresh** to load new entries and **Export** to download the log.

![The Activity Log searched for Demo · Support Triage, with one Updated entry expanded to show the Changes made to its ACL.](./security-and-access-control-activity-log-changes.png)

To see the history of one record, choose **Show History** in the record's actions menu. It opens the Activity Log filtered to that record.

Audit entries are kept for the number of days set in **Administration** → **Automation** (**Audit logs**).

## Troubleshooting security and access control

### A user cannot see an agent that exists

The user has no ACL entry on the agent, directly or through a team. Add the user or one of their teams to **Read Access** (to view) or **Execute Access** (to use) on the agent's **Access Control** tab, then check the result in **ACL Rules**.

### A sidebar page such as Models or Secrets is missing

The page requires the Admin role. Ask your identity provider administrator to assign the role; ACL entries alone do not unlock these pages.

### An agent with PII masking returns an error for every request

PII masking is fail-closed: when the PII detector cannot be reached, requests to agents with **Handles personal data** turned on fail on purpose. Ask your STAIR administrator to check the PII service. Agents without the switch keep working.

### A team member lost access after leaving a team

Permissions granted through a team end when the person leaves the team. In **ACL Rules**, select the person and choose **Via teams** to see which permissions came from teams.

## FAQ

### Does the LLM provider see personal data?

Not for agents with **Handles personal data** turned on. STAIR replaces the selected PII entity types with placeholders such as `<PERSON_1>` before the request reaches the LLM, and restores the real values in the answer.

### What happens if the PII detector is down?

Requests to agents with PII masking fail instead of sending unmasked data. This fail-closed behavior applies only to agents that have **Handles personal data** turned on.

### What is the difference between a role and an ACL?

A role is assigned in the identity provider and decides which kinds of objects you can work with. An ACL is set on each record and decides who can read, write, manage or execute that one record.

### Can I give access to a whole team?

Yes. Every ACL picker accepts teams, and all team members get the permission. **ACL Rules** shows whether a person's permission came directly or **Via teams**.

### Where can I see who changed an agent?

Open the agent's actions menu and choose **Show History**, or open **Activity Log** and search by the agent's name. Expand an entry to see the exact changes.

## Related

- [API Keys and Service Accounts](/docs/api-keys-and-service-accounts/llm.md)
- [AI Agents](/docs/ai-agents/llm.md)
- [Secrets](/docs/secrets/llm.md)
- [Toolsets and MCP Tools](/docs/toolsets-and-mcp-tools/llm.md)
- [Classifications](/docs/classifications/llm.md)
- [STAIR Administration](/docs/stair-administration/llm.md)
- [STAIR Concepts](/docs/stair-concepts/llm.md)