How to scale user access tiers

Correction (2026-08-02, verified against canonical origin/main): this READ/USER/INPUT tier model and the /v1/tokens list/issue/revoke REST API below don't exist — same systemic finding as Pair a new device and Rotate keys and capability tokens. The real PairingRole enum has exactly 3 roles (User/Admin/Interface), and the real API is POST /v1/invite + /v1/pair, not a token-management REST surface. Flagged, not resolved.

User access tiers determine what platform operations a session can perform. As a deployment grows, the administrator needs to promote users from read-only access (READ) to standard session access (USER) or full operator access (INPUT). This guide covers identifying current tier assignments, promoting individual users, and bulk-updating a set of users as a team scales.

For the authorization model that defines tiers, see Machine-based authorization. For issuing the tokens that encode tier assignments, see Issue a capability token.

Prerequisites

• Administrator access to the token issuance service
• A list of users to promote with their current public keys or device identifiers
• A tenant namespace already configured (see Configure a tenant namespace)

The three access tiers

Promote users to the minimum tier that their role requires. Over-privileged sessions create unnecessary audit surface.

Step 1: List current tier assignments

Query the tenant's active tokens to see current tier assignments:

curl -s "http://<issuance-service-host>:<port>/v1/tenants/<tenant-id>/tokens" \
  -H "Authorization: Bearer <admin-token>"

The response lists active tokens with their scope, subject_pubkey, and expires_at fields. Note which users are at READ or USER scope if they need promotion to INPUT.

Step 2: Promote an individual user

To promote a user, issue a new token at the higher scope. The old token remains valid until it expires or is explicitly revoked — there is no in-place upgrade.

Issue a new token:

curl -X POST http://<issuance-service-host>:<port>/v1/tokens \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_pubkey": "<user-pubkey>",
    "scope": "input",
    "tenant_id": "<tenant-id>",
    "expires_in_seconds": 86400
  }'

Deliver the new token to the user. Once they load it, their console session gains the new tier.

Step 3: Revoke the old lower-tier token

After the user confirms the new token is working, revoke the old lower-tier token to close the transition window:

curl -X DELETE http://<issuance-service-host>:<port>/v1/tokens/<old-token-id> \
  -H "Authorization: Bearer <admin-token>"

Revoking the old token ensures there is no simultaneous READ and INPUT credential for the same device — a single session holds exactly one tier at any time.

Step 4: Bulk-update a team

For team-scale promotions, prepare a list of public keys and issue tokens in sequence. A simple shell loop over a JSON file of public keys works:

while IFS= read -r pubkey; do
  curl -X POST http://<issuance-service-host>:<port>/v1/tokens \
    -H "Authorization: Bearer <admin-token>" \
    -H "Content-Type: application/json" \
    -d "{\"subject_pubkey\": \"$pubkey\", \"scope\": \"user\", \"tenant_id\": \"<tenant-id>\", \"expires_in_seconds\": 86400}"
done < pubkeys.txt

Log each issued token ID. After the team confirms their new tokens work, run a corresponding revoke loop over the old token IDs.

Key takeaways

• Tier promotions require issuing a new token; existing tokens cannot be upgraded in place
• Keep the transition window short — revoke the old token after the user confirms the new one works
• Over-privileged sessions inflate audit surface; issue the minimum tier for each role
• WORM ledger entries are created for every token issuance and revocation — tier changes are permanently auditable

See also

• Machine-based authorization — the authorization model that defines what each tier permits
• Issue a capability token — detailed steps for issuing a single capability token
• Rotate keys and capability tokens — replacing a token at expiry or after a suspected compromise
• Configure a tenant namespace — setting up the namespace before user tiers are assigned
• Verify a WORM ledger entry — confirming token issuance events in the audit ledger