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 sort roughly by generation time while 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. The ordering depends on the generating computer's clock, so it is not a strict guarantee. 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, a value the reference implementation chose because it is easy to remember, 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; the format's authors describe it as providing over 100 years of life. 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. Selecting "Generate KSUID" again creates 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. Version 4 UUIDs carry 122 random bits and no timestamp, so two of them give no clue about which one was created first. In its usual text form a UUID is 36 characters: 32 hexadecimal digits in groups separated by hyphens.

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 in a "hex-and-dash" format (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 format was created by Segment, which publishes the reference Go implementation.

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. That is 64 times the number space of the 122 random bits in a version 4 UUID. 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. ksuid: K-Sortable Globally Unique IDs (README). github.com/segmentio/ksuid — 20-byte layout, 27-character base62 text, May 2014 epoch with over 100 years of life, 128 random bits, loose time ordering.
2. Segment. ksuid.go. reference implementation source — epoch constant 1400000000 ("14e8").
3. IETF. RFC 9562: Universally Unique IDentifiers (UUIDs). rfc-editor.org — hex-and-dash text format and the 122 random bits of a version 4 UUID.