UUID v4 Generator Guide — Random IDs for APIs and Databases

Every API and database needs unique identifiers. Auto-increment integers are simple but leak information about record counts and require a central coordinator. UUID v4 solves both problems with 122 bits of cryptographically random data, generated independently by any node in your system.

This guide covers UUID v4 structure, when to choose it over alternatives, and how to generate compliant identifiers using the UUID Generator and backend libraries.

What Is UUID v4?

A UUID v4 (Universally Unique Identifier, version 4) is a 128-bit identifier where 122 bits are random and 6 bits encode the version and variant per RFC 4122.

9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
|______||_||_||_||__________|
  time-  ver var random data
  low    (=4)

The version nibble (the 4 in position 13) confirms this is a v4 UUID. The variant bits ensure compatibility with the UUID standard.

UUID v4 vs Other Versions

For most modern APIs and databases, v4 is the default choice. Read the UUID v1 vs v4 comparison if you need time-ordered IDs or are migrating from v1.

Collision Probability

With 122 random bits, UUID v4 provides approximately 5.3 × 10^36 possible values. To put collision risk in perspective:

• Generating 1 billion UUIDs per second for 100 years gives roughly a 1-in-a-billion chance of a single collision
• For a database with 1 trillion records, collision probability remains negligible

You do not need a central ID server. Each application instance can generate UUIDs independently.

Generating UUID v4

Browser Tool

Open the UUID Generator, select v4, and click Generate. The tool uses crypto.getRandomValues() for cryptographically secure randomness — the same quality as backend CSPRNGs.

Generate multiple IDs at once for bulk database seeding or test fixtures.

Node.js

const { randomUUID } = require('crypto');

const id = randomUUID();
// 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

// Bulk generation
const ids = Array.from({ length: 100 }, () => randomUUID());

Node.js 14.17+ includes randomUUID() natively. For older versions, use the uuid package:

const { v4: uuidv4 } = require('uuid');
const id = uuidv4();

Python

import uuid

id = str(uuid.uuid4())
# '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'

Go

import "github.com/google/uuid"

id := uuid.New().String()

PostgreSQL

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email TEXT NOT NULL
);

Enable the pgcrypto extension if gen_random_uuid() is unavailable:

CREATE EXTENSION IF NOT EXISTS pgcrypto;

Database Design Considerations

Primary Keys

UUID v4 works well as a primary key in distributed systems:

• No coordination required between application instances
• Safe to expose in URLs without revealing record counts
• Merge-friendly across database shards

Tradeoffs to consider:

• Index size — 16 bytes vs 4–8 bytes for integers
• Insert performance — random UUIDs cause B-tree index fragmentation in some databases
• Readability — harder to communicate verbally than sequential IDs

URL-Safe Alternatives

If you need compact URL identifiers, consider removing hyphens:

const compact = randomUUID().replace(/-/g, '');
// 9b1deb4d3b7d4bad9bdd2b0d7b3dcb6d — 32 hex characters

Do not confuse compact UUIDs with other hex ID formats — document your convention.

UUID v4 in API Design

REST Resource IDs

GET /api/users/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
POST /api/orders  →  { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", ... }

Validate UUID format on input to reject malformed IDs early:

const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;

function isValidUuidV4(id) {
  return UUID_REGEX.test(id);
}

JWT `jti` Claim

Use UUID v4 for the jti (JWT ID) claim to enable per-token revocation:

const token = jwt.sign(
  { sub: userId, jti: randomUUID() },
  secret,
  { expiresIn: '15m' }
);

API Keys

UUID v4 is a common format for API keys with 122 bits of entropy:

sk_live_9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

For higher entropy requirements, use 256-bit hex keys instead.

When NOT to Use UUID v4

• High-write tables where insert order matters — consider UUID v7 (time-ordered) or database sequences
• Human-readable reference numbers — use prefixed sequential IDs (ORD-00042)
• Deterministic IDs from user input — use UUID v5 with a fixed namespace

Best Practices

• Generate UUIDs server-side for authoritative records; client-generated IDs are acceptable for optimistic UI patterns with conflict resolution
• Store as native UUID type in PostgreSQL, not as strings (saves space and enables index optimization)
• Validate format on API input — reject malformed IDs with 400, not 404
• Use the UUID Generator for test data, not production records

What to Read Next

• UUID v1 vs v4 comparison
• How to generate UUID v4 in Node.js, Python, and Go
• Generate API keys best practices
• UUID v4 glossary