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

# Token Perks

> Give employees a private personal AI budget that is completely separate from corporate usage analytics.

Token Perks is a privacy-isolated personal AI usage budget. Each enrolled employee gets a monthly token allowance they can use for personal AI work — separate from their corporate allocation and invisible to corporate analytics. This guide explains how to set up tiers, enroll employees, configure rollovers and bonuses, and understand what "privacy-isolated" actually means.

## What Token Perks is

Token Perks gives employees a **personal AI budget** that:

* Is funded separately from department or org-level corporate budgets.
* Never appears in corporate usage dashboards, efficiency scores, or audit logs.
* Can be used during personal projects, side work, or any AI usage the employee wants to keep private.
* Is managed by a **dual-ledger architecture**: personal usage events flow through a completely separate data pipeline, ensuring they never enter the corporate analytics stream.

<Info>
  Admins can see **aggregate** Token Perks data (total tokens consumed across all enrolled users, tier utilization) at **Perks → Admin**. Admins cannot see individual users' personal usage sessions, prompts, or model choices.
</Info>

## Employee enrollment

### Self-service at /perks

Employees enroll themselves by visiting the **Perks Portal** (`PerksPortalPage`) at `/perks`. The self-service flow:

<Steps>
  <Step title="Open the Perks Portal">
    Navigate to `/perks` in the Toktra dashboard, or follow the link in the enrollment invite email.
  </Step>

  <Step title="Review the privacy notice">
    Read the notice explaining what Token Perks tracks (aggregate monthly token counts only) and what it does not track (session content, prompt text, model choices).
  </Step>

  <Step title="Opt in">
    Click **Opt In** to activate Token Perks. You can opt out at any time from the same page — personal data is anonymized on opt-out.
  </Step>
</Steps>

<Note>
  An employee must first be **enrolled** by an admin before they can opt in. Enrollment enables the feature for a user and assigns their tier. Opt-in is the employee's affirmative consent to activate it.
</Note>

### Admin enrollment

To enroll an employee, navigate to **Perks → Admin** and assign the user to a tier. Alternatively, use the API:

```json theme={null}
POST /v1/perks/admin/enroll
{
  "user_id": "usr_abc123",
  "tier_name": "senior-engineer"
}
```

## Role-based tier configuration

Admins configure **tiers** that define the monthly token budget for each role and seniority level. Navigate to **Perks → Admin → Tiers** to manage tiers.

### Creating a tier

<Steps>
  <Step title="Open Tier Configuration">
    Go to **Perks → Admin → Tiers** and click **New Tier**.
  </Step>

  <Step title="Define the tier">
    Enter the tier name, target role or seniority level, and the monthly token budget:

    ```json theme={null}
    POST /v1/perks/tiers
    {
      "tier_name": "senior-engineer",
      "role": "engineer",
      "seniority": "senior",
      "monthly_token_budget": 500000,
      "hard_cap": false,
      "rollover_enabled": true,
      "rollover_cap_pct": 0.5,
      "priority": 10
    }
    ```
  </Step>

  <Step title="Save">
    The tier is created immediately and available for assignment.
  </Step>
</Steps>

Example tier structure:

| Tier              | Monthly budget   | Rollover cap |
| ----------------- | ---------------- | ------------ |
| `ic-engineer`     | 200,000 tokens   | 50%          |
| `senior-engineer` | 500,000 tokens   | 50%          |
| `staff-engineer`  | 1,000,000 tokens | 75%          |
| `manager`         | 300,000 tokens   | None         |

## Monthly token rollover

Unused tokens from each month can roll into the next month up to a configurable cap. Rollovers are calculated automatically on the first day of each month.

**How it works:**

* At month end, Toktra calculates each enrolled user's unused balance (budget − used tokens).
* The rollover amount is `min(unused_balance, budget × rollover_cap_pct)`.
* The rolled-over tokens are added to the user's starting balance for the new month.
* The rollover ledger is viewable by the employee at **Perks → Rollover History**.

<Tip>
  Set a rollover cap to prevent balances from accumulating indefinitely. A 50% cap is a common starting point — it rewards consistent engagement without creating very large unused balances that distort planning.
</Tip>

## Bonus token grants

Admins can configure **bonus rules** that automatically grant additional tokens when an employee meets a condition.

Common bonus triggers include:

* Completing a training module or certification
* Achieving a high efficiency score for the month
* Participating in an AI adoption program

### Creating a bonus rule

Navigate to **Perks → Admin → Bonus Rules** or call the API:

```json theme={null}
POST /v1/perks/bonus-rules
{
  "rule_name": "Complete AI Safety Training",
  "trigger_event": "training_completed",
  "trigger_metadata": { "training_id": "ai-safety-101" },
  "bonus_tokens": 100000,
  "enabled": true
}
```

Toktra evaluates all active bonus rules nightly and grants tokens to qualifying employees. Employees can view their bonus grant history at **Perks → Bonus History**.

## Personal mode toggle

When an employee is enrolled in Token Perks, they can switch between **corporate mode** (usage tracked against the org budget) and **personal mode** (usage tracked against their personal perks balance) directly from the agent or browser extension.

* **macOS agent:** Click the Toktra menu bar icon and toggle **Personal Mode**.
* **Chrome / Edge extension:** Open the extension popup and click the **Personal Mode** toggle.

When personal mode is active, usage events are routed through the personal data pipeline instead of the corporate analytics pipeline. This routing is enforced server-side and cannot be bypassed.

<Warning>
  Personal mode must be explicitly activated by the employee before each session. The default state is always corporate mode. Toktra does not automatically infer intent — the employee controls the toggle.
</Warning>

## What "privacy-isolated" means

Token Perks uses a **dual-ledger architecture** to guarantee that personal usage never enters corporate analytics:

1. **Separate data pipeline:** Personal events are routed through an isolated pipeline. The corporate analytics stream never receives personal events.
2. **90-day TTL:** Personal usage data is automatically deleted after 90 days.
3. **Envelope encryption:** Personal usage data is encrypted with per-user keys. The per-user key is required to read any personal usage record — even Toktra administrators cannot access it.
4. **Scoped access control:** Personal usage storage is scoped per-user in addition to per-organization. Tenant admins cannot query individual personal usage records.
5. **Admin view is aggregate only:** The admin Perks dashboard shows only aggregated metrics (total tokens consumed across the org, tier utilization) — no per-user breakdown.

## Reimbursement integration

If your organization reimburses employees for personal AI spending, Toktra can integrate with your reimbursement workflow. Navigate to **Reimbursements** in the dashboard to submit, approve, and export reimbursement requests. Approved requests can be exported to Expensify or SAP Concur via the `/v1/reimbursements` API.

## Checking your balance

Employees can check their current personal balance at any time:

```
GET /v1/perks/balance
```

The response includes base tokens, rollover balance, bonus balance, and total balance:

```json theme={null}
{
  "base_tokens": 500000,
  "rollover_balance": 125000,
  "bonus_balance": 100000,
  "total_balance": 725000,
  "tier_name": "senior-engineer"
}
```