# API v3 token and account permissions

> 2026-11-11 · Explicit account-wide link, QR and analytics grants, narrower defaults for new keys, compatibility for existing integrations, and themed permission controls.

API v3 separates links created by one API key from all links belonging to its account. V3 is recommended for new integrations; v1 and v2 remain supported.

- New v3 keys use token-scoped link, QR and analytics grants. A default key can create and read its own links without gaining access to links created by other integrations or the dashboard.
- `user:links:read`, `user:links:write` and `user:links:delete` explicitly authorize those operations across the same account. `user:analytics:read` and `user:qr:read` provide separate account-wide access to visitor data and QR downloads.
- The `account_read_only` preset includes account-wide link and QR reads plus available-domain discovery. It does not include analytics, editing, deletion or key management.
- A compatibility migration adds matching account grants to existing v3 keys to preserve their previous operations. Existing empty keys receive only explicit profile/email grants to preserve their previous `/me` fields; new empty keys expose diagnostics only. Legacy and session credentials retain their existing account access.
- Link lists, totals and individual resource endpoints apply the same scope. Out-of-scope resources return 404 before input validation. Cross-account access still requires `admin:links` and a current administrator role.
- Dashboard creation and settings now use shared, labeled checkboxes with permission descriptions, dashboard colors and keyboard focus indicators.
- Discovery and OpenAPI describe the new vocabulary and scope alternatives.

Operators must deploy the migration and code together during a maintenance window. The [v3 reference](https://docs.ternis.link/api-v3) explains rollout, rollback and how to narrow an existing integration. Keys, quotas and existing response shapes otherwise keep their current behavior.

Account grants now use the `user:` prefix. Independent `user:info` and `user:email` grants control profile fields in `/me`; new keys omit both by default. Existing credentials are preserved by a compatibility migration.
