> ## Documentation Index
> Fetch the complete documentation index at: https://trytilde.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# IAM

> Control what operators, agents, and end users can do in Tilde: identities, fine-grained agent capabilities, channel access, and token lifetimes.

Tilde has three kinds of principal, and each is governed differently:

* **Operators** manage the registry through the UI or the management API. See [Operator access](/docs/operator-access).
* **Agents** act during invocations, within the capabilities you grant them.
* **End users** talk to agents through chat channels, within each channel's access policy.

## Identities

| Identity | Authenticates with | Used for |
| - | - | - |
| Operator | An OIDC login from your identity provider, in Cloud and Enterprise. | The Tilde UI and management API. |
| Management API key | A bearer key, shown once and stored only as a hash. Cloud and Enterprise only. | CI pipelines and automation. |
| Agent deployment | A deployment token, shown once and stored as a hash. | Connecting to the gateway and waiting for work. Nothing else. |
| Agent invocation | A signed token that lasts five minutes. | Every tool call, LLM request, and telemetry upload in one invocation. |
| Ingress client | A scoped ingress token, optionally restricted to one thread. | Your own apps that post to native Tilde chat. |
| End user | A channel identity, such as an email address, phone number, or username. | Talking to agents through chat channels. |

### Operators and API keys <span className="cloud-tag">CLOUD</span><span className="enterprise-tag">ENTERPRISE</span>

Operators sign in through your identity provider, and hold roles that decide what they can see and change. Automation uses management API keys, which hold roles in the same way. Agent runtimes never receive operator tokens. See [Operator access](/docs/operator-access).

## Agent capabilities

Capabilities are the fine-grained permissions of an agent. They decide what the agent can do during an invocation. The gateway enforces them on every call, so they hold even if the agent's code or prompt is compromised.

Three rules apply throughout:

* **Deny by default.** A new agent has no capabilities. A capability you do not grant is denied.
* **Signed into the token.** The gateway writes the agent's capabilities into each invocation token, and verifies them on every runtime call.
* **Narrow only.** Renewing a token can keep or reduce its authority, and can never add to it. In Cloud and Enterprise, an operator cannot grant more than they hold.

### Capability reference

| Capability | Type | Lets the agent |
| - | - | - |
| `tools.invoke` | Targeted, by tool name | Call the named tools. |
| `tools.personal` | Targeted, by provider | Use the personal tools of the user it is serving. |
| `agents.invoke` | Targeted, by agent | Invoke other agents in the current thread. |
| `agents.read` | Targeted, by agent | Read other agents' registry entries. |
| `agents.update` | Targeted, by agent | Update other agents. |
| `agents.delete` | Targeted, by agent | Delete other agents. |
| `agents.grant_capabilities` | Targeted, by agent | Grant capabilities to other agents, up to its own. |
| `agents.edit_prompts` | Targeted, by agent | Delete the prompt histories of agents, itself included. |
| `agents.edit_skills` | Targeted, by agent | Assign and unassign skills on agents, itself included. |
| `skills.read` | Targeted, by skill group | See the groups, and assign their skills. |
| `skills.edit` | Targeted, by skill group | Write skills into editor groups, and sync Git and catalog groups. |
| `agents.create` | Yes or no | Register new agents. |
| `thread.read` | Yes or no | Read the conversation thread it is working in. |
| `work.read` | Yes or no | Read goals and tasks. |
| `work.write` | Yes or no | Create and update goals and tasks. |
| `run.update` | Yes or no | Change the status of its run. |

### Targeted capabilities

A targeted capability takes one of three modes:

* **None** denies the action.
* **All** allows it for every target.
* **Selected** allows it for a list of targets that you choose.

Prefer **Selected**. An agent that only replies to users needs `tools.invoke` for `sendMessage`, and nothing more.

### Set capabilities

<Tabs>
  <Tab title="Tilde UI">
    Open the agent in the Agent Registry and select **Capabilities**. Changes save immediately.
  </Tab>

  <Tab title="Management API">
    Set the same capabilities through the management API when you create or update an agent, for example from your infrastructure-as-code pipeline.
  </Tab>
</Tabs>

### When a change takes effect

A capability change applies to new invocations at once, and reaches running invocations within minutes, when their tokens renew. Stop controls abort an agent's work immediately.

### Permissions beyond capabilities

Some agent permissions are assignments rather than capabilities. The gateway enforces these too.

| Permission | Where you set it | Effect |
| - | - | - |
| Inference connections | The agent's **Inference** tab | The agent can send LLM requests only through its assigned connections. The list is signed into each token. |
| Inference budgets | The agent's **Inference** tab | A blocked budget removes the connection from the agent's next token. See [Inference providers](/docs/inference-providers#budgets). |
| Channel connections | The agent's **Chat providers** tab | The agent receives messages only from its assigned channels. |
| Security policy | The agent's **Security** tab | Guards screen the agent's input and output. Tilde Enterprise only, for now. See [Security middleware](/docs/security/middleware). |

## End-user access

You control who can talk to an agent on each channel connection.

| Access mode | Who can message the agent |
| - | - |
| **Private** | Only identities you have allowed. |
| **Public** | Anyone who can reach the channel. |
| **Disabled** | No one. |

In private mode, allow individual identities, such as an email address or phone number. Tilde can also ask a user to verify an identity before it links that identity to them. An operator can attest an identity instead, and Tilde records who made the attestation.

Tilde enforces channel access in the database, on every message. It checks the sender before [security middleware](/docs/security/middleware) runs, and before the agent sees anything.

## Token lifetimes

Every credential in Tilde is either short-lived or revocable.

| Token | Lifetime | Revocation |
| - | - | - |
| Operator session | Eight hours | Logout revokes it. Cloud and Enterprise. |
| Management API key | Until revoked | Takes effect within seconds. Cloud and Enterprise. |
| Deployment token | Until rotated or retired | Immediate. |
| Invocation token | Minutes, renewed while work is active | Renewal is blocked when the invocation ends or access is lost. |