Course contentsShow
← System Design
Lesson 1017 of 1,91926. Idempotency and RetriesFree lesson

Idempotency Key Scope and Namespacing

Scope idempotency keys appropriately per user, tenant, or operation type to avoid collisions and simplify key management.

Idempotency Key Scope and Namespacing

What you'll learn: How to scope idempotency keys properly to prevent collisions and simplify key management across different users, tenants, and operations.

The Problem with Global Keys

If you use raw idempotency keys (like UUIDs) without context, you risk collisions or inappropriate reuse. Imagine User A submits payment with key abc-123, and User B accidentally uses the same key—your system might mistakenly treat User B's request as a duplicate of User A's. Even worse, a malicious user could intentionally reuse keys to extract information about other users' operations.

Namespacing Idempotency Keys

Namespacing means combining the idempotency key with additional scope identifiers to create a unique composite key:

effective_key = "{user_id}:{operation_type}:{client_key}"

For example:

  • User 42's payment: user:42:payment:abc-123
  • User 99's payment: user:99:payment:abc-123
  • User 42's refund: user:42:refund:abc-123

Now the same client-provided key (abc-123) is safely isolated across different contexts.

Common Scoping Strategies

Per-User: Keys are scoped to individual users, preventing cross-user interference.

Per-Tenant: In multi-tenant systems, scope by tenant ID to isolate entire organizations.

Per-Operation-Type: Different operations (payment, refund, transfer) use separate namespaces, allowing key reuse across different actions.

Hierarchical: Combine multiple levels: tenant:acme:user:42:payment:abc-123

Think of It Like Apartment Addresses

"Unit 5" means nothing without a building address. Similarly, an idempotency key needs context (user, tenant, operation) to be truly unique and safely reusable across different contexts.

Key Takeaway: Always namespace idempotency keys with user, tenant, or operation-type prefixes to prevent collisions, improve security, and make debugging easier—never treat client-provided keys as globally unique.