Edit: UUID v4 Generator Guide — Random IDs fo…

Posts›UUID v4 Generator Guide — Random IDs fo…

PublishedView Live →

Title

Slug

Preview: https://jwtsecretgenerator.com/blog/uuid-v4-generator-guide

⚠ Changing the slug will break existing links to this post.

Description / Excerpt

157 / 180 characters

Content (Markdown)

# 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](/tools/uuid-generator) and backend libraries.

## What Is UUID v4?

A [UUID v4](/glossary/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

| Version | Source | Sortable | Use Case |
|---------|--------|----------|----------|
| v1 | MAC address + timestamp | Yes (roughly) | Legacy systems needing time ordering |
| v4 | Random | No | General-purpose unique IDs |
| v5 | SHA-1 hash of namespace + name | No | Deterministic IDs from known inputs |

For most modern APIs and databases, v4 is the default choice. Read the [UUID v1 vs v4 comparison](/compare/uuid-v1-vs-v4) 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](/tools/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

```javascript
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:

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

### Python

```python
import uuid

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

### Go

```go
import "github.com/google/uuid"

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

### PostgreSQL

```sql
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:

```sql
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:

```javascript
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:

```javascript
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:

```javascript
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](/tools/uuid-generator) for test data, not production records

## What to Read Next

- [UUID v1 vs v4 comparison](/compare/uuid-v1-vs-v4)
- [How to generate UUID v4 in Node.js, Python, and Go](/blog/how-to-generate-uuid-v4)
- [Generate API keys best practices](/blog/generate-api-key-best-practices)
- [UUID v4 glossary](/glossary/uuid-v4)

822 words · ~5 min readMarkdown guide →

Tags (3/8)

uuidgetting-startednodejs

Author Name

Status

Cover Image URL (optional)

Danger Zone

Deleting this post sets its status to "deleted". It can be recovered via the API.