Audience: Admin frontend developers Scope: Digital key pool CRUD managed by catalog admins

Digital Key Module - API & Integration Guide

1. Quick Metadata

• Module: Catalog / Digital Key
• Auth: JwtAuthGuard + RoleGuard + @Permissions(DigitalKeys_*)
• Surface: Admin only
• Base route: /api/admin/catalog/products/:productId/keys

2. Overview

Digital key pools are managed reference records for digital products (e.g., software licenses, activation keys). Each digital product has a pool of keys that are assigned to customers at delivery time. This module provides admin CRUD for managing the key pool. There are no public or mobile digital-key endpoints in the current repo.

3. Route Summary

4. Query Parameters

List keys (GET /api/admin/catalog/products/:productId/keys)

5. Response Shapes

KeyResponseDto

{
  "id": 1,
  "productId": 42,
  "keyValue": "XXXXX-YYYYY-ZZZZZ-11111",
  "status": "available",
  "assignedAt": null,
  "assignedOrderId": null,
  "assignedOrderItemId": null,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

• status can be available, assigned, or expired.
• assignedAt, assignedOrderId, assignedOrderItemId are null until the key is assigned to an order.
• keyValue is hidden from mobile/customer surfaces — admin only.

KeySummaryResponseDto

{
  "productId": 42,
  "total": 100,
  "available": 85,
  "assigned": 15,
  "expired": 0
}

AddKeysResponseDto

{
  "inserted": 5,
  "skipped": 0
}

• inserted — number of new keys added to the pool.
• skipped — number of duplicate keys that already existed.

DeleteKeyResponseDto

{
  "keyId": 1,
  "status": "deleted"
}

6. Request Examples

Add keys (bulk)

POST /api/admin/catalog/products/42/keys
{
  "keys": [
    "AAAAA-BBBBB-CCCCC-11111",
    "DDDDD-EEEEE-FFFFF-22222"
  ]
}

List keys

GET /api/admin/catalog/products/42/keys?page=1&size=20&status=available

Get key summary

GET /api/admin/catalog/products/42/keys/summary

Delete a key

DELETE /api/admin/catalog/products/42/keys/1

7. Error Handling

8. Integration Notes

• Keys are created in available status only.
• Keys cannot be updated — only added or deleted.
• Deleting a key is only allowed when status is available.
• Duplicate keys (same productId + keyValue) are silently skipped using onConflictDoNothing.
• Key assignment (available → assigned) happens during digital delivery — not through this API.

See Also

• Digital Key - Backend Documentation
• Order Fulfillment Lifecycle