# Choosing token and account permissions in API v3

> 2026-11-11 · Give each integration the links it needs, and use explicit account grants when a reporting tool needs to span multiple tokens and dashboard links.

A publishing integration and an account reporting tool need different access. The publisher usually needs to create links and manage the ones it created. The reporting tool needs to see links created by several integrations and by people using the dashboard. API v3 makes that choice explicit and is now the recommended version for new integrations. V1 and v2 remain supported.

## Start with one integration’s links

New v3 keys default to the `link_creator` preset: `links:read`, `links:write`, `domains:read` and `qr:read`. The link and QR permissions cover links created by that key. Links created by another token, a session or the dashboard stay outside that scope. Knowing a link ID does not grant access.

Analytics and deletion are separate choices. Add `analytics:read` if the integration needs visitor statistics for its links, or `links:delete` if it needs to deactivate them. Neither is included by default.

## Choose account access deliberately

An account reporting tool can use this explicit permission list:

```json
{
  "name": "Account reporting",
  "permissions": ["user:links:read", "user:analytics:read"]
}
```

Here, `user` means all links in the same account, including links created by other keys and the dashboard. It does not mean other users’ accounts. Each account grant includes its corresponding operation, so selecting both `links:read` and `user:links:read` is unnecessary.

For an inventory tool that needs links and QR codes without visitor data, choose `account_read_only`. Account-wide editing and deactivation require their own `user:links:write` and `user:links:delete` grants. Cross-account administration still requires an explicit `admin:links` grant and a current administrator role.

## Profile information

`/me` always exposes permission and quota diagnostics. Profile name requires `user:info`; email independently requires `user:email`. Neither is included in the standard presets. No wildcard or duplicate `self:` permissions are accepted.

## Review existing keys and replacements

The compatibility migrations preserve existing v3 access, rename old `:all:` grants to `user:` grants, and add explicit profile/email grants for fields previously returned unconditionally. It keeps old integrations working without giving them unrelated operations. An operator must deploy this migration with the code before reopening traffic. After deployment, inspect `/v3/me` or the dashboard key settings to see the exact grants and remove broader ones where appropriate.

A newly generated replacement key has its own scope; it does not inherit the old key’s link attribution. Use the appropriate account grants if the replacement must access historical links. Revoking a key keeps its links intact.

The dashboard describes every permission beside a checkbox in its current theme. Choose a preset, review the grants, and keep key management separate from routine publishing. An API caller may delegate only permission names already present in its effective grants.

See the [API v3 reference](https://docs.ternis.link/api-v3) for the complete operation matrix, compatibility details and deployment instructions.
