UUID Security

The core distinction: identifier versus secret

A UUID gives you a value that is practically unique — something nothing else will collide with. That is useful. What it does not give you is a value that is unguessable by an authorised party in the way a password is. The two properties are often conflated, and confusing them leads to real vulnerabilities.

A password is a shared secret between you and an authentication system. Its security rests on the fact that only you know it, the system never stores it in plaintext, and guessing it is computationally expensive. A UUID v4 is 122 bits of randomness from a cryptographic source — yes, it is also practically unguessable — but it has no surrounding security properties. It is not hashed before storage, it appears in URLs, it travels in HTTP headers, and any system that processes a URL containing it likely logs it.

Use UUIDs as identifiers. Use proper secrets (from crypto.getRandomValues, crypto.randomBytes, or a purpose-built library) when you need a credential.

What UUID v4 actually guarantees

UUID v4 draws its 122 non-fixed bits from the platform’s CSPRNG — the same source backing crypto.randomUUID() in browsers and crypto.randomUUID() in Node.js. That means:

• Collision resistance. The probability of two independent generators producing the same v4 is approximately 1 in 2¹²². You would need to generate roughly 2.7 × 10¹⁸ UUIDs before a collision became likely. This is a solved problem for practical use.
• Unpredictability. Given any number of previously generated v4 UUIDs, an attacker cannot predict the next one. The output is indistinguishable from random bytes.
• No information leakage. A v4 UUID reveals nothing about when it was made, what machine made it, or what came before or after it.

What v4 does not guarantee:

• Secrecy in transit. If the UUID is in a URL, it is in logs, browser history, referrer headers sent to third-party scripts, and any link previewer the user runs.
• Access control. Knowing an identifier does not mean you should be able to use it. An API that accepts any UUID without validating the caller’s identity has no authorisation model.
• Resistance to side-channel leaks. Timing differences in string comparison, UUID reuse across tenants, or predictable UUIDs from a poorly seeded non-crypto source (common in some test environments) can all break the unpredictability property.

What UUID v7 leaks and when that matters

UUID v7 encodes a Unix millisecond timestamp in its high bits. This is intentional and useful for database indexes. It is a disclosure risk when the identifier is externally visible.

What anyone holding a v7 UUID can learn:

• The exact millisecond the record was created.
• By comparing two v7 UUIDs, how much time elapsed between their creation.
• By collecting a series of v7 UUIDs from an application, an approximation of its transaction or sign-up rate.

When this matters:

• User-facing URLs. A POST /orders response that returns a v7 UUID in the Location header tells the client (and any party that can observe the URL) exactly when the order was placed.
• Shared links. A file share, invitation, or document URL built on a v7 UUID reveals when the document was created.
• Enumeration proximity. v7 is not sequentially guessable — the low bits are still random — but knowing a timestamp range dramatically reduces the search space for adjacent records if access controls are weak.

The standard recommendation: use v7 for internal primary keys where creation time is harmless or useful; use v4 for any identifier that leaves the system boundary.

Common mistakes

Using a UUID as an API key

An API key is a credential. It proves that the caller is authorised. A UUID in a header field can authenticate in the trivial sense of “this is a string I issued you,” but it has no revocation, no rotation, and no binding to an identity. If the key leaks — via a log file, a curl history entry, or an environment variable — there is no way to detect the leak or limit its blast radius.

Use a purpose-built API key format: an opaque 256-bit value from a CSPRNG, prefixed with a product identifier so it can be detected by secret-scanning tools (like GitHub’s push protection), stored as a hash on the server side.

Treating a UUID in a URL as access control

A UUID share link (for a document, a file, a payment page) is sometimes called a “capability URL” — knowing the URL is proof of access. This is legitimate for low-stakes sharing but it is not a substitute for authentication:

• Server logs record every URL accessed. If a third party can read your logs, they have every capability URL ever visited.
• The Referer header sends the full URL to third-party scripts on the destination page.
• Browsers sync history, and history is often accessible to browser extensions.

For anything sensitive, require authentication in addition to the URL token, and set a short expiry.

Generating UUIDs with Math.random()

Math.random() is a pseudo-random number generator seeded from a low-entropy source. It is deterministic and produces numbers that are not cryptographically random. Any UUID built from Math.random() outputs has far less than 122 bits of real entropy — in some JavaScript engine versions, the effective entropy is below 60 bits. Always use crypto.randomUUID() or crypto.getRandomValues().

Reusing UUIDs

An ID that gets recycled — for example, one that is deleted and then reinserted — carries the risk that authorisation decisions made on the old record apply to the new one, or that caches return stale data. Treat UUIDs as write-once and immutable.

Choosing between v4 and v7 from a security standpoint

Randomness source checklist

Before shipping UUID-based security-sensitive code, verify:

• Generation uses crypto.randomUUID() or crypto.getRandomValues() — never Math.random()
• UUIDs in URLs are paired with authentication for sensitive resources
• Server logs are treated as sensitive if they contain UUID capability URLs
• v7 UUIDs are not used in externally visible identifiers where timestamp is a disclosure
• The UUID is never the only access control — it is always an identifier, not an authenticator