figma guide
Designing API keys and personal access tokens UI in Figma: scopes, rotation, and developer security settings
Design API keys and personal access tokens UI in Figma with create/revoke flows, scope pickers, one-time secret display, rotation, and Dev Mode specs for developer security settings.
- Published
- Updated
- Jul 09, 2026
- Read time
- 7 min
- Level
- Intermediate
Quick answer
API keys and personal access tokens (PATs) let developers authenticate scripts and integrations programmatically—usually under Account → Developer, Settings → API, or Organization → Integrations. Design a token list with name, masked prefix, scopes, created/last-used dates, and Revoke; a create flow with name, expiration, scope checkboxes, and one-time secret display (copy once, never shown again); plus rotation and last-used metadata for hygiene. Keep this separate from connected OAuth apps—keys are bearer secrets, not user-delegated consent screens. After compromise, link from account recovery review. Start from the Figma guides hub and pair with Dev Mode handoff for engineering specs.
Who this is for
- Product designers building developer settings for SaaS APIs, CLI tools, and automation platforms.
- Design system teams distinguishing PAT UI from OAuth app directories and admin API credentials.
- Engineers implementing scoped tokens, hashing at rest, rotation without downtime, and audit events.
API keys vs OAuth apps vs service accounts
| Credential type | Who creates | Typical use | UI home |
|---|---|---|---|
| Personal access token | End user | Scripts, CI, local dev | User Developer settings |
| OAuth connected app | User authorizes third party | ”Sign in with”, calendar sync | Connected accounts |
| Org service account | Admin | Server-to-server, ETL | Admin → Integrations |
| Publishable client key | Developer | Browser SDK (limited) | App settings with domain allowlist |
| Webhook signing secret | Auto-generated | Verify payloads | Webhook detail page |
Verdict: never list PATs beside consumer “Google connected” rows—different mental model, different revoke consequences. Mention in copy that revoking a key breaks automations immediately.
Token list row anatomy
| Part | Spec | Notes |
|---|---|---|
| Name | User-defined label | ”CI deploy”, “Local dev” |
| Prefix | sk_live_abc… masked | Show first 8 + ellipsis |
| Scopes summary | Chips or comma list | read:orders, write:products |
| Created | Date | |
| Expires | Date or “Never” | Encourage expiry |
| Last used | Relative time or “Never” | Stale key hygiene |
| Revoke | Destructive text button | Confirm modal |
ApiKeyListRow
├── Variant: status=active | expired | revoked
├── Variant: stale=true | false (e.g. unused 90d)
└── Layers:
├── KeyIcon
├── NameLabel
├── PrefixBadge
├── ScopeChips
├── MetaLine (created · expires · last used)
├── StaleWarning (conditional)
└── RevokeButtonLink View in activity log to audit log when keys are created or revoked.
Create token flow
| Step | UI | Validation |
|---|---|---|
| 1. Name | Text input | Required, 3–64 chars |
| 2. Expiration | 7 / 30 / 90 days, 1 year, custom | Default 90 days |
| 3. Scopes | Grouped checkboxes with descriptions | At least one; warn on admin |
| 4. Confirm | Summary + re-auth password or 2FA | Step-up for sensitive scopes |
| 5. Secret reveal | Full token + copy button + download | One-time only |
| 6. Done | ”You won’t see this again” | Link back to list |
Secret reveal screen:
┌─────────────────────────────────────────────┐
│ Copy your token now │
│ ┌─────────────────────────────────────┐ │
│ │ sk_live_xxxxxxxxxxxxxxxxxxxxxxxx │ 📋 │
│ └─────────────────────────────────────┘ │
│ ☐ I have stored this token securely │
│ [ Done ] (disabled until checkbox) │
└─────────────────────────────────────────────┘Reuse patterns from 2FA recovery codes—same one-time display discipline.
Scope picker design
| Pattern | Best for |
|---|---|
| Grouped checkboxes | < 20 scopes in 4–6 categories |
| Search + multi-select | Large API surface |
| Preset bundles | ”Read only”, “Full access” with expand |
| Danger tier | Red label on delete:*, admin:* |
| Scope tier | UI treatment | Extra gate |
|---|---|---|
| Read | Standard checkbox | None |
| Write | Standard | Optional confirm copy |
| Admin / billing | Warning icon | Re-auth + typed confirm |
| Impersonation | Rare; separate flow | Enterprise policy |
Document scope strings verbatim in Dev Mode—engineers map 1:1 to authorization middleware.
Rotation and dual-key workflow
| Pattern | UX | Engineering note |
|---|---|---|
| Rotate in place | New secret; old valid 24h | Grace period banner on list |
| Create new + revoke old | Manual two-step | User manages overlap |
| Auto-expire | Email 7 days before | Link to create replacement |
Rotation modal copy: “A new token will be generated. The current token stops working on Jul 12, 2026 at 3:00 PM UTC.”
Show both prefixes during overlap on the list with Expiring badge on the old row.
Empty, error, and revoked states
| State | Copy / UI |
|---|---|
| Empty list | ”No tokens yet” + Create CTA + link to API docs |
| Revoked | Row moves to collapsed “Revoked” section or disappears after 30d |
| Expired | Gray row + “Create replacement” |
| Rate limited create | ”Too many tokens—revoke unused keys” |
| Org policy disabled | ”Your admin disabled personal tokens” |
Stale key nudge: banner when 3+ keys unused 90 days—“Review unused tokens” with bulk revoke optional.
Security settings page layout
| Section | Contents |
|---|---|
| Header | ”API tokens” + docs link |
| Policy note | ”Treat tokens like passwords” |
| Create button | Primary, top-right |
| Active tokens | Table or card list |
| Revoked / expired | Collapsible archive |
| Org settings link | Admin-only service accounts |
Place under Developer or Advanced in account dashboard—not inside consumer Profile. Cross-link privacy when tokens access personal data exports.
Audit, compliance, and recovery
Log these events to security activity:
| Event | Severity |
|---|---|
| Token created | Info |
| Token revoked | Info |
| Token used from new IP (optional) | Warning |
| Admin disabled PATs for org | Warning |
| Leaked key reported (GitHub scan) | Critical + auto-revoke email |
Post-account recovery, show “Review API tokens” with keys used during incident window highlighted.
Mobile and responsive considerations
| Breakpoint | Pattern |
|---|---|
| Mobile | Card list; scope chips wrap; revoke in overflow menu |
| Secret reveal | Monospace scroll; copy via Web Share API optional |
| Desktop | Table with sort by last used |
Never show full secret on mobile push notifications or email—creation confirmation email lists name + prefix only.
Handoff checklist
| Item | Dev Mode annotation |
|---|---|
| Token format | Prefix + entropy length |
| Hash at rest | Only prefix stored for display |
| Scope enum | Full list with descriptions |
| Expiration options | Default selection |
| Grace period on rotate | Hours |
| Last used timestamp | UTC, update throttled |
| Revoke confirmation | Modal copy + irreversible note |
| a11y | Copy button announces success; secret not in aria-label |
| Rate limits | Max active tokens per user |
For CLI docs, specify env var name (API_TOKEN) in a comment layer—not in user-facing UI unless product is developer-first.
Common mistakes
| Mistake | Why it hurts | Fix |
|---|---|---|
| Showing full key after create step | Leak via screenshot history | One-time reveal only |
| OAuth UI mixed with PAT list | Wrong revoke expectations | Separate pages |
| No expiration default | Keys live forever | Default 90 days |
| Scopes without descriptions | Over-permissioned tokens | Plain-language scope help |
| Revoke without confirmation | Broken production CI | Modal with token name |
| ”Regenerate” without grace | Instant outage | Overlap window |
| Missing last-used | No stale key cleanup | Show relative last used |
| Email contains full secret | Inbox breach = API breach | Prefix only in email |
Recommended workflow
- Inventory scopes with API team—group for checkbox UI.
- Design list row with prefix, scopes, dates, revoke.
- Build create wizard through one-time secret reveal.
- Add rotation with grace period and dual-prefix list state.
- Wire audit events to security activity feed.
- Link from account recovery review checklist.
- Separate from OAuth in IA and connected accounts navigation.
- Prototype expired token and re-auth on admin scope create.
FAQ
Personal access tokens vs OAuth for my integration?
OAuth when a third-party app acts on behalf of a user with consent screens. PATs when the user owns the script (CLI, notebook, personal automation).
How many active tokens should we allow?
Common caps: 10–25 per user; show count toward limit on create. Enterprise may allow more via admin policy.
Support “view secret again”?
No. Industry standard is create new + revoke old. Explain in empty-state docs link.
Org-level vs user-level keys?
User PAT = that user’s permissions. Service account = non-human, admin-provisioned—separate admin UI, not covered by the same list component.
Browser-exposed keys?
Never for full secrets—use short-lived session or publishable keys with domain restrictions. Full PAT creation only in authenticated settings, not embeddable widgets.
Next steps
- Design connected accounts and OAuth linking UI in Figma — user-delegated apps, not bearer tokens
- Design audit log and security activity UI in Figma — token created/revoked events
- Design suspicious login alerts and account recovery UI in Figma — post-breach token review
- Figma Dev Mode for designers: handoff checklist — annotate scope enums and token format
- Best Figma dev handoff plugins (Inspect, tokens, code) — if pairing with API documentation handoff
§ Keep reading