Skip to content

We use analytics cookies to see how the site is used. They are only set if you accept. Accepting also turns on session recording (pages viewed, clicks and scrolls) so we can fix problems; what you type stays hidden. It also lets Meta (Facebook) see your visit, so we can measure our ads. Read the privacy policy

An API key shown masked to its prefix and last four characters, next to the SHA-256 hash the database keeps instead of the key.

Safety data sheet / APIs / 9 min read

API Key Format: Prefixes, Checksums and Hashed Storage That Catch Leaks Early

How to design the keys your API hands out: a prefix scanners can match, a random part nobody can guess, a checksum, a hash in the database, and a plan for the day one leaks.

Danger

A live API key acts as its owner. Show it once, store a hash, never commit it.

Hazard class: bearer secret

A well-made API key has three parts: a prefix that names your product and the key type, a long random secret, and a short checksum. The full key is shown once, the database keeps only a hash of it, and the prefix is registered with secret scanners, so a leaked key gets reported to you and revoked.

What should an API key look like?

GitHub moved to this shape in April 2021, and its write-up is the clearest public reference: a prefix such as ghp_, 30 random characters, then a checksum, a 32-bit CRC32 value written as the last 6 characters, all "without changing the token length". Here is the same shape for a made-up product called acme:

A key made by the code further down: a 10-character prefix, 32 random base62 characters and a 6-character CRC32 checksum.
Prefix
Says whose key it is and what kind. Lets a scanner find it with a simple pattern, and lets a person see at a glance that a string is a live secret.
Random secret
The part that does the work. Long enough that nobody can guess it, drawn from a cryptographic random source.
Checksum
A few characters computed from the rest. A scanner can tell a real key from a look-alike string without asking your API.

The underscore is a deliberate choice too. GitHub picked it because it is not a Base64 character, so random strings such as hashes rarely contain one, and because a double click "will reliably select the whole token".

Why does the format matter when a key leaks?

Because keys leak all the time, and the format decides how fast someone notices. GitGuardian counted 28,649,024 new secrets in public GitHub commits in 2025, about a third more than in 2024. Of the valid secrets it found in 2022, it reports that 64% were still active four years later.

A scanner can only report what it can recognize. A 40-character hex string looks like any Git commit hash; ghp_ followed by 36 characters looks like one thing only. GitHub expected that the prefix alone would bring the false positive rate for secret scanning down to 0.5%, and that the checksum would make false positives virtually disappear.

The idea has a standard as well: RFC 8959 (January 2021) registers a secret-token: URI scheme so that tokens are "easier to unambiguously identify" in source code repositories and CI systems. The vendor prefixes in the next section do the same job in a shorter form.

Which key prefixes do the big APIs use?

GitHub and Slack put the issuer and the key type in the prefix. Stripe's prefixes name the key type and the environment, so a test key is easy to tell from a live one.

VendorPrefixWhat it isSource
GitHubghp_Personal access token (classic)GitHub blog
GitHubgithub_pat_Fine-grained personal access tokenGitHub Docs
GitHubgho_ / ghu_ / ghs_ / ghr_OAuth, user-to-server, server-to-server and refresh tokensGitHub blog
Stripesk_live_ / sk_test_Secret key, live or sandboxStripe Docs
Stripepk_live_ / pk_test_Publishable key, safe in a browserStripe Docs
Striperk_live_ / rk_test_Restricted key with limited permissionsStripe Docs
Slackxoxb- / xoxp-Bot token / user tokenSlack Docs

Three rules follow from the table. Make the prefix unique to you: a generic sk_ alone does not say whose key it is. Put the key type in it, so a publishable key and a secret key never look alike. Put the environment in it if you have one, so a log line shows at once whether production is at risk.

Should the key carry a visible ID?

It can. The open source Prefixed API Key pattern builds keys as prefix, short token and long token, for example mycompany_BRTRKFsL_51FwqftsmMDHHbJAMEXXHCgG. The server stores the short token as is, to find the record, and only a hash of the long token. Slack's tokens are split too: sections are separated by a hyphen, and "the final section is the secret".

How long should the random part be?

Long enough to give at least 112 bits of randomness, and there is no reason to stop there. Each character drawn from the 62 letters and digits adds about 5.95 bits, so 19 characters clear 112 bits and 30 give the 178 bits GitHub quotes for its OAuth access tokens. The 112-bit line is the minimum security strength NIST SP 800-63B-4 uses for look-up secrets.

  1. 16 characters 95 bits
  2. 19 characters 113 bits
  3. 30 (GitHub) 178 bits
  4. 32 characters 190 bits
  5. 43 characters 256 bits
Bits of randomness in a secret of random base62 characters (length times log2 of 62, rounded down). The dashed red line marks 112 bits; the bar below it is pale. Math by us; the 112-bit line is from NIST SP 800-63B-4, the 178 bits from GitHub.

Two details matter more than the exact number. Use the operating system's cryptographic random source (crypto.randomBytes in Node.js, secrets in Python), never Math.random. And when you map random bytes to 62 characters, drop the byte values 248 to 255 instead of taking every byte modulo 62, or the first eight characters of the alphabet come up more often.

How does the checksum work?

Compute CRC32 over the prefix and the random part, encode the 32-bit result in base62 and append it. Six base62 characters hold any 32-bit number. A scanner, a CLI or your own API can then reject a mistyped or made-up key without a database lookup. CRC32 is a check against typos and look-alike strings, not a security feature: anyone can compute it, which is the point.

How do you generate a key like this?

In Node.js it takes under 40 lines and no dependencies. zlib.crc32 was added in Node.js 22.2.0 and 20.15.0.

import { randomBytes, createHash } from 'node:crypto'
import { crc32 } from 'node:zlib'

const ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'

function randomBase62(length) {
  let out = ''
  while (out.length < length) {
    for (const byte of randomBytes(length * 2)) {
      if (byte < 248) out += ALPHABET[byte % 62] // 248 = 62 * 4, so no character is favoured
      if (out.length === length) break
    }
  }
  return out
}

function checksum(text) {
  let n = crc32(text)
  let out = ''
  for (let i = 0; i < 6; i++) {
    out = ALPHABET[n % 62] + out
    n = Math.floor(n / 62)
  }
  return out
}

export function createApiKey(prefix = 'acme_live_') {
  const body = prefix + randomBase62(32)
  const key = body + checksum(body)
  const hash = createHash('sha256').update(key).digest('hex')
  return { key, hash } // show key once, store hash
}

export function looksLikeOurKey(key, prefix = 'acme_live_') {
  if (typeof key !== 'string' || !key.startsWith(prefix) || key.length !== prefix.length + 38) return false
  return checksum(key.slice(0, -6)) === key.slice(-6)
}

On each request, run looksLikeOurKey first, then hash the key and look the hash up. A request with a malformed key never reaches the database.

How should you store API keys?

Store a hash, never the key. If the key table leaks, the attacker gets hashes that do not work as keys. That is also why such keys are shown only once. Stripe says of secret keys you create yourself: "you can't reveal it after you've seen it once".

acme_live_5aFUNrYIPbqmGi2XMEDDMPFbvSFQMhFW1shsFOWhat the dashboard shows later

Which hash? For passwords, OWASP says fast hashes "such as SHA-256 are not suitable", because people pick guessable passwords. A random key with 190 bits, like the one above, cannot be guessed, so the slow hash buys nothing. NIST makes the same split for look-up secrets: hashed with an approved hash function, and salted with a slow password hash only when a secret is shorter than 112 bits. That rule is written for look-up secrets, not API keys, but the reasoning carries over. A plain SHA-256 also lets you find the record by its hash in one indexed query.

Pros of storing only a hash

  • A database dump or backup leak does not hand out working keys.
  • Staff with database access cannot copy a customer's key.
  • One indexed lookup per request, no decryption key to guard.

Cons, and how to live with them

  • A lost key cannot be shown again: the user creates a new one.
  • Users need a way to tell keys apart: store a name, the prefix and the last 4 characters for display.
  • Rotation needs two keys valid at once for a while: allow several active keys per account.

How do you get told when one of your keys leaks?

Join GitHub's secret scanning partner program. You give GitHub a name for your secret type, a regular expression that matches your keys, a test account and an endpoint. GitHub then scans public repositories and public npm packages, and when it finds a match it calls your endpoint. Its docs list the same ingredients as best practices for identifiable secrets: "a uniquely defined prefix", "high entropy random strings" and "a 32-bit checksum".

  1. 1. git pushCommits a file that contains acme_live_... to a public repository.
  2. 2. matchGitHub matches the string against the pattern you registered.
  3. 3. POST to your endpointA JSON array of objects with token, type, url and source, signed in the Github-Public-Key-Signature header.
  4. 4. verifyYour API checks the ECDSA P-256 signature against GitHub's published public keys, then looks up the token's hash.
  5. 5. revoke and notifyTreat the key as public, revoke it and tell its owner where it was found.
The partner program flow, from GitHub's secret scanning partner program docs. GitHub asks partners to treat every reported secret "as public and compromised".

Verify that signature before you act on the request, as with any webhook; our post on webhook signature verification covers the general pattern. GitHub also stops some secrets before they land: push protection is on by default for pushes to public repositories (rolled out from February 2024), for the secret types it supports, though a user can bypass it.

What should you do when a key leaks?

Write the runbook before you need it. The order below follows the partner program's suggestion to revoke and notify; the times are our suggested targets, not a standard.

  1. T+0

    Confirm the report

    Check the scanner's signature, run the checksum and find the key by its hash. A key you never issued needs no further action.

    Automated
  2. T+5 min

    Revoke the key

    Disable it at once. Waiting for the owner to rotate it leaves it working while it is public.

    Automated
  3. T+10 min

    Tell the owner

    Email the account owner which key, where it was found (the url from the report) and how to create a new one.

    Automated
  4. T+1 h

    Check for misuse

    Look through the request logs for that key between the commit time and the revocation: unknown IPs, unusual endpoints, data exports.

    On-call engineer
  5. T+1 day

    Close the loop

    Confirm the owner has a working replacement and the leaked file is gone or rewritten, and note what made the leak possible.

    Support

If keys leak from your users' code, a fast rate limit per key also caps what a stranger can do with one before you revoke it.

Questions developers ask about API key design

Is a UUID good enough as an API key?

A version 4 UUID has 122 random bits, above the 112-bit line, so it is hard to guess. It has no prefix and no checksum, though, so a scanner cannot tell it from any other UUID in a log or a repository.

Should I encrypt API keys instead of hashing them?

Only if you must show the key again later. Encryption means the key can be recovered by anyone who gets both the database and the encryption key. Hashing means nobody can, which is why keys are usually shown once.

Can I change the format of keys I already issued?

Yes, for new keys. Accept both formats, issue only the new one, and ask users to rotate. In 2021 GitHub added its prefixes "without changing the token length", but its newer formats are longer (github_pat_) or shaped differently, and GitHub's docs warn apps that expect installation tokens to be exactly 40 characters long, now that a new format is rolling out. Do not hard-code a length in clients; check the prefix instead.

Does a prefix help attackers?

It tells them a string is a key, which a leaked key's context usually does anyway. It tells defenders the same thing, and defenders run scanners on every public push. The random part is what keeps the key safe, not the secrecy of its format.

Sources

  1. GitHub blog: Behind GitHub's new authentication token formats (April 5, 2021, updated May 10, 2023: prefixes, underscore, CRC32 checksum, 178 bits, 0.5% false positives)
  2. GitHub Docs: About authentication to GitHub (token prefixes, github_pat_, the note on 40-character installation tokens)
  3. GitHub Docs: Secret scanning partner program (what partners provide, payload, signature, revoke and notify)
  4. GitHub Docs: About push protection and GitHub blog: Keeping secrets out of public repositories (February 29, 2024)
  5. Stripe Docs: API keys (prefixes, reveal once) and Stripe Docs: Best practices for managing secret API keys
  6. Slack Docs: Tokens (xoxb-, xoxp-, sections)
  7. RFC 8959: The "secret-token" URI Scheme (January 2021)
  8. GitGuardian: The State of Secrets Sprawl 2026 (28,649,024 secrets in 2025; 64% still active)
  9. NIST SP 800-63B-4 (look-up secret storage, 112-bit minimum)
  10. OWASP Password Storage Cheat Sheet (fast hashes and passwords)
  11. Seam: prefixed-api-key (prefix, short token, long token)
  12. Node.js Docs: zlib.crc32
  13. RFC 9562: Universally Unique IDentifiers (122 random bits in a version 4 UUID)

Related: publishing npm packages without a long-lived token.