Outcome
By the end of this lesson, you will be able to create and scope a PAT correctly, explain why the decision happens at call time rather than at mint time, and choose the right naming and expiry for traceable rotation.
| Prerequisites | T4.M4.1 (RBAC) · M6.1 (MCP concept) |
| Time | 9 minutes |
1. Concept
A Personal Access Token is a long string that stands in for you when a program talks to ZopNight on your behalf.
Whoever holds it can act as you, which is why the rest of this lesson is about handling it carefully.
ZopNight’s are deliberately simple. A token carries your identity rather than a narrower one, so what it can read follows your role, resolved fresh on every call. Two things are chosen at mint: which of your organisations it may act in, and which write capabilities it carries, which may be fewer than you hold. They can be revoked at any time, and replaced without downtime.
ZOPNIGHT PAT PROPERTIES: Format: zn_pat_xxxxxxxxxxxxxxxx (32-char identifier) Reads: Whatever your role allows, resolved on every call Writes: Only the capabilities ticked at mint, and never more than your live role and the org tier admit Org-bound: Bound at mint to the orgs you pick (only orgs you belong to); membership and your live policies are still checked on every call Expiry: 30 days, 90 days (default), 1 year, no expiry, or a custom date Revocable: Can be revoked anytime in Settings → API & MCP Tied to user: Remove the user from an org and their PATs stop reaching it on the next callWhat a PAT grants
A token declares intent. The gateway decides:
USER: jane@team.comROLE: EngineerPOLICIES: resource:view, schedule:view+create, recommendation:view+apply
A WRITE CALL NEEDS ALL THREE: the token carries that write capability, ticked at mint your live role permits the action, read now not at mint the org's MCP write tier admits it, none by defaultThe two axes behave differently, and keeping them apart is the whole of this lesson. Your role is not narrowable by the token: it carries your identity, not a smaller one, so it reads exactly what you can read, and a role change takes effect on the next request with no re-mint. Write capability is narrowable: a token minted with none cannot write even where your role could, which is the point of a read-only token in CI.
On a default org the write tier is none, so the intersection is reads only however the token was minted. Every write, at any tier, also needs a token bound to the organisation it acts in, which is why you pick the orgs at mint.
Why the decision happens at call time, not at mint time
MINT TIME asks: what may this token ever try?CALL TIME asks: is this caller allowed to do it right now?Freezing the second answer into the token would mean carrying around an authorisation state computed on one particular afternoon.
WHAT CALL-TIME ENFORCEMENT BUYS YOU
role elevated the existing token starts working; no reissue role narrowed the next call fails; no revocation step, no window tier enabled existing tokens reach the tier's tools tier disabled they stop, everywhere, at onceThe de-escalation row is the one that matters. A token holding a snapshot taken while a role was wide stays wide until somebody remembers to replace it. A token that is re-checked fails the moment the role narrows.
One consequence worth knowing: a token can be minted for something its holder is not yet entitled to run. It simply fails until the role allows it, which lets the credential and the entitlement be two decisions, made by two people, at two times.
Multiple PATs per user
A user can have many PATs (one per device, one per integration). Each PAT is independent: revoke one without affecting the others.
EXAMPLE USER PATs: laptop-desktop: PAT for Claude Desktop on laptop workstation: PAT for Claude Desktop on workstation cursor: PAT for Cursor IDE on laptop ci-bot: PAT for CI/CD agent that reads MCP
NAMING matters: easier to revoke or rotate the right one when a device is lost.Non-human users (service accounts)
For automation, bots, and CI/CD agents:
RECOMMENDED: Create a dedicated user (e.g., ci-bot@team.com) with appropriate role Generate a PAT for that user Treat the user as the bot's identity
NOT RECOMMENDED: Use a human user's PAT for bots → Loses traceability ("who did this action?") → If human leaves, bot breaks → Auditor concernsThe dedicated-user pattern keeps human and bot activity cleanly separated in audit logs.
Expiry mechanics
PAT EXPIRY: Options at mint: 30 days, 90 days (default), 1 year, no expiry, or any custom date from tomorrow After expiry, the token returns 401 on all API calls Rotate keeps the token, issues a new secret and can set a new expiry; the old secret stops working at once
TYPICAL EXPIRY CHOICES: 90 days: Standard for personal MCP integrations (the default) 1 year: CI bots (with stricter rotation discipline) 30 days or a custom date: Temporary access for contractors / pilots No expiry: Avoid; if you must, rotate on a schedule anyway90-day expiry is the most common starting point. Longer expiry is acceptable when paired with strong rotation discipline.
PAT vs API key
PAT: CLOUD-NATIVE API KEY: ZopNight-specific Cloud provider (AWS/GCP/Azure) User-tied Often service-account-tied Write capabilities set at mint Various scopes Rotated via ZopNight UI Rotated via cloud provider Audit in ZopNight log Audit in cloud provider log
Don't confuse them. ZopNight's PAT authenticates against ZopNight;cloud-provider keys authenticate against the cloud.Storage best practices
DO: Store in secrets manager (1Password, Vault, AWS Secrets Manager) Load from environment variable in MCP config One PAT per device; rotate per device on loss Clear, specific PAT names
DON'T: Commit to source control Paste in chat / Slack / email Share PATs between users Reuse a PAT across multiple devices (loses isolation) Store in plain text files without strong file permissionsThe PAT is a bearer token: possession is authorization. Treat like a password.
What the audit trail records per call
Every MCP call is logged in the audit log under the person behind it, never with the token secret:
AUDIT LOG ENTRY: Timestamp: 2026-05-21T14:32:00Z User: jane@platform Source: mcp Tool called: list_resources Request: {sort: idle_days} Status: 200 (read responses are not stored)The entry does not yet record which of your tokens made the call, so the audit log cannot tell your laptop’s token from your workstation’s. Per-device tokens still pay off: when a device is lost, you revoke that one token and the others keep working.
2. Demo
A clean PAT lifecycle over 90 days:
T+0 jane@team.com creates a PAT for Claude DesktopT+0:30 Settings → API & MCP → Create Token Name: "Claude Desktop on jane-mbp 2026-Q2" Expiry: 90 days Generated: zn_pat_8f9a3b... (copied immediately; shown only once)
T+1 day Jane uses MCP from Claude DesktopT+1 day Each MCP call: - Authenticated by zn_pat_8f9a3b... - Authorized by jane's policies (Engineer role) - Logged in audit: user=jane@team.com, source=mcp, the tool and its arguments
T+30 days No usage anomalies in audit log; PAT working normally
T+83 days Jane's calendar reminder fires (the token's expiry date is shown in Settings → API & MCP)
T+85 days Jane creates a new PAT (same name pattern with Q3) Updates Claude Desktop config to new PAT Verifies new PAT works (asks "Who am I?" via MCP) Revokes the old PAT in ZopNight settings
T+90 days Old PAT's expiry date passes (already revoked)
NEXT CYCLE: Same pattern repeats for Q3The 5-minute rotation, repeated each quarter, keeps PAT exposure bounded.
3. Hands-on (5 min)
Create your own PAT:
□ STEP 1: Open ZopNight → Settings → API & MCP□ STEP 2: Click "Create Token"□ STEP 3: Configure: Name: __________ (specific: "tool on device YYYY-QN") Organizations: __________ (only the ones this token needs) Expiry: 90 days (default) or __________ Write capabilities: none for a read-only token, or __________
□ STEP 4: Copy the token immediately (shown only once)□ STEP 5: Store securely: □ 1Password / Bitwarden / secrets manager □ Environment variable in ~/.zshrc (with 0600 perms on file) □ Cloud secrets manager (AWS Secrets, etc.)
□ STEP 6: Configure in your MCP tool (see M6.2)□ STEP 7: Verify connection (see M6.2.L4)
REVIEW your existing PATs: Total PATs: _____ Any with vague names? _____ Any >75 days old? _____ (plan rotation)If you have PATs with vague names (“test”, “for stuff”), replace them.
4. Knowledge check
Q1
A PAT grants:
A. All access, since a PAT bypasses the role model entirely
B. Your identity for reads, plus the write capabilities ticked at mint
C. A fixed read-only scope, whichever user happens to hold it
D. Exactly the policies its user held on the day it was minted
Show answer
Correct: B. Reads follow your identity, which the token cannot narrow and cannot widen. Writes need the capability ticked at mint as well, and are then checked against your role as it stands now and the org’s write tier. D is the mint-time snapshot model, and its weakness is de-escalation: a token minted while a role was wide would stay wide until somebody replaced it.
Q2
A user has 5 PATs. The user is removed from the org. The PATs:
A. Keep reaching that org until they expire
B. Stop reaching that org on the next call
C. Convert to org tokens
D. Stay active but drop to a read-only scope
Show answer
Correct: B. Identity and membership are re-resolved on every call, so a removed user’s tokens stop reaching that org at once, with no separate revocation step. This is also why bots should use a dedicated user, not a human’s PAT: when a person leaves, the bot should not break.
Q3
For a CI/CD bot needing MCP access:
A. Reuse the PAT belonging to whichever engineer set it up
B. Mint an org-level token with no individual user behind it at all, shared across the whole pipeline
C. Hardcode a human user’s own credentials into the job
D. Create a dedicated user (e.g., ci-bot@team.com) with appropriate role, then create a PAT for that user
Show answer
Correct: D. The bot’s activity is not conflated with a person’s, the bot keeps working when people leave, and auditors can see exactly what the bot did.
5. Apply
Settings → API & MCP supports multiple PATs per user. Pattern: one PAT per device with specific naming; rotate per device on loss; quarterly rotation policy for ongoing hygiene.
For bots: dedicated user with own role + PAT. Documented in your team’s secrets-management runbook.
Related lessons
- L2: Org-level MCP toggle (next)
- L3: Audit logging for MCP
- L4: PAT rotation
- T4.M4.1: RBAC fundamentals