Skip to main content

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 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.
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.

​
Employee enrollment

​
Self-service at /perks

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

Open the Perks Portal

Navigate to /perks in the Toktra dashboard, or follow the link in the enrollment invite email.
2

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).
3

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.
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.

​
Admin enrollment

To enroll an employee, navigate to Perks → Admin and assign the user to a tier. Alternatively, use the API: 
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

1

Open Tier Configuration

Go to Perks → Admin → Tiers and click New Tier.
2

Define the tier

Enter the tier name, target role or seniority level, and the monthly token budget:
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
}
3

Save

The tier is created immediately and available for assignment.
Example tier structure:
TierMonthly budgetRollover cap
ic-engineer200,000 tokens50%
senior-engineer500,000 tokens50%
staff-engineer1,000,000 tokens75%
manager300,000 tokensNone

​
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.
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.

​
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: 
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.
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.

​
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: 
{
  "base_tokens": 500000,
  "rollover_balance": 125000,
  "bonus_balance": 100000,
  "total_balance": 725000,
  "tier_name": "senior-engineer"
}