KSUID Generator - Create Sortable Unique Identifiers

KSUID generator

A KSUID (K-Sortable Unique Identifier) is a 27-character code used to label records such as database rows, log entries, or API requests. It combines a timestamp with random data, so IDs made later always sort after IDs made earlier, even though each one is still effectively unique. This tool generates a single KSUID in the browser and lets the user copy it.

What is a KSUID made of?

A KSUID is 20 bytes long, split into two parts:

• Timestamp (4 bytes): the number of seconds since a fixed starting point called the KSUID epoch.
• Random payload (16 bytes): data produced by the browser's cryptographic random number generator.

Those 20 bytes are then converted into text using base62 encoding, a system that represents numbers using 62 characters: the digits 0-9, the uppercase letters A-Z, and the lowercase letters a-z. The result is always padded to exactly 27 characters, for example 0qjBBlJIfbVLKwnJn4xpLGDr00e.

Because the timestamp comes first, two KSUIDs made a second apart will normally sort in the same order as their creation times when compared as plain text. Because the last 16 bytes are random, two KSUIDs made in the same second are still almost certain to be different.

KSUID epoch

Most computer systems count time in seconds since January 1, 1970 (the "Unix epoch"). KSUIDs use a different starting point, the KSUID epoch: 1,400,000,000 seconds after the Unix epoch, which is May 13, 2014, 16:53:20 UTC.

Using a later starting point lets the 4-byte timestamp field cover more useful years before it runs out of room. A 4-byte (32-bit) counter can hold at most 4,294,967,295 seconds. Counting from the KSUID epoch, that stretch of time runs out around June 19, 2150.

KSUID formula

A KSUID string is built in three steps.

1. Find the timestamp value:

   T = floor(current_unix_time_in_seconds) − 1,400,000,000

2. Generate 16 random bytes, R, using a cryptographically secure random number generator.

3. Join the 4-byte timestamp and the 16 random bytes into one 20-byte block, then encode that block in base62, padding the result to 27 characters:

   KSUID = Base62( T ‖ R )

Here ‖ means "place one after the other." The timestamp bytes always come first, which is what makes the final string sort correctly by time.

Worked example

Suppose the timestamp portion of a KSUID is 100000000. Since the KSUID epoch is 1,400,000,000 seconds after the Unix epoch, this timestamp represents July 14, 2017, 02:40:00 UTC.

Pair that timestamp with the 16-byte sequence 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 (used here only to keep the example reproducible; a real generator uses random bytes instead) and the base62 encoding produces:

0qjBBlJIfbVLKwnJn4xpLGDr00e

That string is 27 characters long, made only of digits and letters, and safe to use directly in a URL or file name.

How to use the KSUID generator tool

1. Open the KSUID generator page.
2. Select the "Generate KSUID" button.
3. The tool creates one new KSUID using the current time and fresh random bytes, and displays it on the page.
4. Select the "Copy KSUID" button to copy the value to the clipboard.
5. Select "Reset" to clear the result and generate a new one.

Each click of "Generate KSUID" produces exactly one identifier. To create several KSUIDs, click the button again for each new one; there is no batch mode or file export built into the tool.

The generator relies on the Web Crypto API built into modern browsers. If that API is unavailable, the tool shows an error instead of producing an ID, because a random number generator that is not cryptographically secure could produce identifiers that are easier to guess or that collide.

KSUID compared with UUID

A UUID (Universally Unique Identifier) is a common alternative identifier format. The most widely used version, UUID v4, is 36 characters long and made almost entirely of random bits, so two UUIDs give no clue about which one was created first.

A KSUID differs in three ways:

• Sortable by time. Its leading timestamp bytes mean plain alphabetical sorting of KSUID strings also sorts them by creation time.
• Shorter. A KSUID is 27 characters, compared to 36 for a standard UUID.
• No separators. A UUID is normally written with hyphens (xxxxxxxx-xxxx-...); a KSUID has none.

Both formats can be generated independently on different computers without checking with a central server, so both avoid the bottleneck of an auto-incrementing counter in a shared database.

Frequently asked questions

What does KSUID stand for? K-Sortable Unique Identifier. The "K" refers to the fact that it is sortable ("kind of sortable" in the original design notes from Segment, the company that created the format).

How long is a KSUID? 27 characters, encoded using base62 (digits 0-9, uppercase letters, lowercase letters).

What is the KSUID epoch? May 13, 2014, 16:53:20 UTC, which is 1,400,000,000 seconds after the standard Unix epoch of January 1, 1970.

Can two KSUIDs collide? It is extremely unlikely. Each KSUID includes 16 random bytes (128 bits), generated with a cryptographically secure random number generator. Even generating many KSUIDs in the same second leaves an astronomically small chance of two matching by accident.

Can I recover the creation time from a KSUID? Yes. The first 4 bytes of the decoded value are the timestamp. Adding that number of seconds to the KSUID epoch gives the original creation time.

Does this tool support generating many KSUIDs at once? No. The tool generates one KSUID per click of the "Generate KSUID" button. There is no quantity input, custom timestamp field, or export/download feature.

Is a KSUID safe to put in a URL? Yes. Base62 encoding uses only digits and letters, so a KSUID needs no extra escaping to appear in a URL, file name, or database key.

References

1. Segment's KSUID GitHub repository: https://github.com/segmentio/ksuid
2. "Generating good unique identifiers" by Peter Bourgon: https://peter.bourgon.org/blog/2019/05/20/generating-good-unique-ids.html