How Should You Design API Key and Token UX?

How Should You Design API Key and Token UX?

Show the secret once, prefix it so it is recognisable, force a name and an expiry, scope it as narrowly as the product allows, and show when it was last used. Most token interfaces get the security right and the human part wrong, which is why so many production systems run on a key called "test" that nobody dares delete.

We design settings and developer-facing screens for B2B products, and the token page is consistently one of the most neglected. It is built once by a backend engineer, it works, and nobody looks at it again until an incident.

Here is what a good one does, using patterns from platforms that have had to solve this at scale.

Why Does Token UX Matter Beyond Security?

Because the interface decides whether people follow your security advice. Documentation can recommend short-lived, narrowly scoped keys all it likes. If your create-token screen defaults to no expiry and full access, that is what everyone will ship.

The same applies to cleanup. Teams accumulate keys nobody can identify, and the reason is almost always that the interface did not require a name or record who created it. You cannot revoke what you cannot identify, so nothing gets revoked.

Good defaults here are worth more than any warning banner. The screen is the policy.

Should Tokens Have a Visible Prefix?

Yes, and there is a well-documented example to copy. GitHub's engineering blog, in a post first published in April 2021, explains that it moved to identifiable three-letter prefixes starting with a company signifier of gh, using ghp for personal access tokens, gho for OAuth access tokens, ghu for user-to-server tokens, ghs for server-to-server tokens and ghr for refresh tokens.

The reasoning is practical. GitHub describes prefixes as a clear way to make tokens identifiable, and says it added an underscore separator because an underscore is not a Base64 character, which helps ensure its tokens cannot be accidentally duplicated by randomly generated strings.

The payoff is detection. GitHub reports adding a 32 bit checksum in the last six digits of each token using a CRC32 algorithm and a Base62 implementation, to virtually eliminate false positives for offline secret scanning, and anticipated that identifiable prefixes alone would bring the secret scanning false positive rate down to 0.5 percent.

What Should Happen at the Moment of Creation?

The secret appears once, prominently, with an obvious copy control and a plain warning that it will not be shown again. Then it is gone. Storing a retrievable copy is convenient for users and a liability for you.

Make the copy action impossible to miss and impossible to mistake. A common failure is a truncated display with an ellipsis where copying selects only the visible portion. Copy the full value to the clipboard, and confirm visibly that it worked.

Offer a way to continue safely if they lose it. "Regenerate" needs to exist, needs to be clearly destructive, and needs to say exactly what will break. Our piece on designing destructive actions covers how to make that unambiguous without being annoying.

Should You Require a Name and a Description?

Require the name. Suggest the description. A required name is the single highest-value field on the form, because it is what makes revocation possible six months later.

Help people write a useful one. A placeholder reading "My token" produces a list of tokens called My token. A placeholder reading "Zapier production sync" produces names people can act on, because it demonstrates what the field is for.

Record the creator and the creation date automatically, and show both in the list. In a team account, "who made this" is the first question asked in every key audit, and it should never require a support ticket.

What Should the Expiry Default Be?

Something finite. A default of no expiry means your oldest credentials are also your most powerful and least remembered, which is exactly backwards.

GitHub's documentation notes that as a security precaution it automatically removes personal access tokens that have not been used in a year, and that organisations can enforce maximum lifetime policies for fine-grained tokens. Both ideas are worth borrowing: a sensible default, plus a way for an administrator to set the ceiling.

If you must allow non-expiring tokens, make it a deliberate choice rather than the default, and surface those tokens distinctly in the list so they are easy to review.

How Granular Should the Permissions Be?

Granular enough that read-only is genuinely read-only. GitHub explicitly recommends using fine-grained personal access tokens instead of classic ones wherever possible, and its documentation describes those tokens as offering specific, fine-grained permissions with more control than the scopes granted to classic tokens.

The other half is resource scoping. GitHub's documentation says each fine-grained token can be limited to only access specific repositories for that user or organisation, where a classic token reaches everything the user can reach. The equivalent in your product is scoping a key to one project, workspace or environment.

The interface challenge is presenting this without a wall of checkboxes. We usually solve it with two or three named presets covering the common cases, plus a custom option for everyone else. Our piece on roles and permissions UX covers the same trade-off for user roles.

What Does the Token List Need to Show?

Name, creator, created date, scope summary, expiry, and last used. Last used is the field teams forget and the field that makes cleanup possible, because it turns "I think this is unused" into a fact.

Show a prefix fragment, never the full secret. Enough characters to match against a value someone has in a config file, not enough to be useful if the screenshot leaks.

Sort by last used rather than by creation date. It puts the stale credentials at the top of the page, which is where the work is.

How Should Rotation and Revocation Work?

Rotation should allow an overlap. If regenerating a key immediately invalidates the old one, every rotation is an outage, so teams avoid rotating. Letting a new key exist alongside the old one for a defined window is what makes the good behaviour possible.

Revocation should be immediate, obvious and logged. Confirm with the token's name typed or selected rather than a generic "are you sure", because the failure mode here is revoking the wrong one in a list of similar entries.

Tell people what happened afterwards. A revoked key should produce a clear, distinguishable error at the API, not a generic 401 that sends an engineer hunting through their own code for an hour.

Who Approves a Key in a Larger Organisation?

Somebody should be able to, and that is a product decision worth making early. GitHub's documentation notes that organisation owners can require approval for any fine-grained personal access token that can access resources in the organisation, which turns key creation from an individual act into a governed one.

For most B2B products, a lighter version is enough: admins can see every key in the account, can revoke any of them, and get notified when one is created with broad scope. That covers the realistic governance need without building an approval queue nobody staffs.

Pair it with an audit trail, because the questions asked after an incident are always about sequence and timing. Our piece on audit log UI design covers what those records need to contain.

What Would We Build First?

If you are starting from a bare list, add three things in this order: a required name, a last-used column, and a finite default expiry. Those three turn an unmanageable list into something a team can actually review, and none of them requires changing your auth system.

After that, prefixes and scoping are the bigger projects, and both are worth doing properly rather than quickly. A prefix scheme is very hard to change once customers have tokens in production, so borrow a proven pattern rather than inventing one.

If you want a second opinion on a developer-facing settings area before you build it, we are happy to walk through it. You can reach our team at phoenix.studio.