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

# Execution policies and role-based access

> Configure automatic versus confirm-required execution, scope actions to user roles, and govern who can trigger writes through your AI agent.

Every action has a policy answering three questions: **who** can trigger it, **when** it requires confirmation, and **what** role conditions apply.

## Governance tiers

### Automatic

The action runs immediately. Use for all read actions, lookups, and autocomplete calls the AI makes silently.

### Confirm required

The AI prepares the full payload, then pauses. The user sees a confirmation panel before anything executes. Use for anything that creates, modifies, or deletes data.

<Warning>
  When in doubt, use Confirm required. It costs the user one click. It prevents a category of mistakes that are expensive to undo.
</Warning>

## Roles

Roles in Candu Actions are a product-layer guardrail: they decide which actions appear to a given user. They are *not* a security boundary. Your API must enforce its own access controls — Candu's role check just prevents the AI from offering an action the user shouldn't see in the first place.

### How role-gating works

There is no separate `role` parameter. You pass the user's role as a key inside the `identifiers` object at `init()` time:

```javascript theme={null}
window.canduAgentik.init({
  userId: "user-123",
  clientToken: "YOUR_CLIENT_TOKEN",
  snippetVersion: "0.2.0",
  identifiers: {
    role: "admin"   // matches role configured on each action
  }
});
```

Candu Actions compares the `role` value against the roles configured on each action in the dashboard. Users always have access to actions configured for **Everyone** regardless of their role. Actions configured for a specific role are only available when the identifier value matches.

| Role     | Who can trigger it                           |
| -------- | -------------------------------------------- |
| Everyone | All users, always                            |
| Manager  | Users where `identifiers.role === "manager"` |
| Admin    | Users where `identifiers.role === "admin"`   |

Role values are arbitrary strings — these are illustrative. Configure whichever role names match your app's existing user types. If no role is passed, or the value doesn't match any configured role, the user still has access to all Everyone actions.

Role gating is evaluated per request. A user whose role changes mid-session will see the available actions update at their next message.

## Identifiers

Identifiers are runtime context values you pass to Candu Actions at `init()` time. It's a free-form key-value object — anything the AI might need at runtime that isn't user-specific.

```javascript theme={null}
window.canduAgentik.init({
  userId: "user-123",           // required
  clientToken: "YOUR_TOKEN",    // required
  snippetVersion: "0.2.0",      // required
  identifiers: {                // optional
    role: "admin",
    organizationId: "org-456",
    workspaceSlug: "my-workspace"
  }
});
```

Beyond gating, identifiers do real work at runtime. Any key in the `identifiers` object is available as a `{variable}` in action endpoint templates — `/api/{organizationId}/segments` resolves at request time from `identifiers.organizationId`. This is how you keep action definitions tenant-agnostic.

Identifiers are injected into the AI's system prompt on every request. They are never written to any database — they're request-scoped only and discarded when the request completes.

## Data and privacy

| Data                      | Persisted                                     |
| ------------------------- | --------------------------------------------- |
| `userId`                  | Yes — used to group runs in the Activity view |
| Identifiers               | No — request-scoped only                      |
| User message text         | Yes                                           |
| Action inputs and outputs | Yes (as JSON)                                 |
| Config files              | Yes — retained until deleted                  |

<Info>
  If your API returns sensitive data in a response body, that data will appear in execution logs. Design your action endpoints to return the minimum necessary response. See [Execution & Logs](/actions/execution) for the full field reference.
</Info>