Generate Secret Key

Generate a cryptographically secure random secret key for secure order lookups without authentication.

Overview

The Generate Secret Key step creates a cryptographically secure random key that can be used to retrieve orders without authentication. This enables use cases like customer order tracking links, guest checkout order retrieval, and third-party integrations.

Identifier

Property	Value
Key	`GenerateSecretKey`
Group	Enrich
Applicable Statuses	New

Configuration Properties

Property	Type	Default	Description
KeyLength	int	16	Length of the generated key (max: 64 characters)
CharacterSet	string	`A-Za-z0-9`	Characters to use for key generation
OverwriteExisting	bool	true	Whether to regenerate if a key already exists

Character Set

The default character set includes:

Uppercase letters: ABCDEFGHIJKLMNOPQRSTUVWXYZ
Lowercase letters: abcdefghijklmnopqrstuvwxyz
Numbers: 0123456789

You can customize this to exclude ambiguous characters (like 0, O, l, 1) or include special characters.

Behavior

What It Does

Checks if the order already has a secret key
If key exists and OverwriteExisting is false, skips generation
Validates and constrains KeyLength to maximum of 64 characters
Loads custom character set or uses default
Generates cryptographically secure random key
Sets SecretKey property on the order
Returns result invisibly (doesn't show in workflow history)

Prerequisites

None. This step can run on any order.

Side Effects

Order.SecretKey property is set
Existing key is overwritten if OverwriteExisting is true

Business Cases

When to Use

Guest order tracking: Provide customers with a secure link to track orders without login
Email notifications: Include order lookup links in confirmation emails
Third-party access: Give partners access to specific orders without full API credentials
Customer service: Generate secure links for customer support scenarios

Example Scenarios

Scenario 1: Standard Generation

Configuration:
- KeyLength: 16
- CharacterSet: (default)
- OverwriteExisting: true

Result: Generates key like "aB3xR9mK2pQw7Vn5"

Scenario 2: Long Key with Custom Characters

Configuration:
- KeyLength: 32
- CharacterSet: ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 (no lowercase)
- OverwriteExisting: true

Result: Generates key like "A3X9M2PQ7VN5B8K4R1Z6Y0C3D7E2F9"

Scenario 3: Preserve Existing Key

Configuration:
- OverwriteExisting: false

Behavior: If order already has a secret key, it won't be regenerated

Using the Secret Key

In Notifications

The secret key can be used in notification templates via the replacement token:

{ORDER_SECRET_KEY}

Example email template:

Track your order here:
https://yoursite.com/track?key={ORDER_SECRET_KEY}

API Endpoint

Orders can be retrieved using the secret key via the public API:

GET /api/orders/secret/{secretKey}

Response: Returns the full OmniumOrder object if the key matches, or 404 if not found.

Security Note: This endpoint does not require authentication. The secret key itself acts as the authorization mechanism.

{
  "ActionType": "GenerateSecretKey"
}

Uses all defaults: 16-character key with alphanumeric characters.

Custom Length

{
  "ActionType": "GenerateSecretKey",
  "Properties": [
    { "Key": "KeyLength", "Value": "24" }
  ]
}

No Ambiguous Characters

{
  "ActionType": "GenerateSecretKey",
  "Properties": [
    { "Key": "CharacterSet", "Value": "ABCDEFGHJKLMNPQRSTUVWXYZ23456789" }
  ]
}

Excludes: I, O, 0, 1, lowercase letters

Preserve Existing Keys

{
  "ActionType": "GenerateSecretKey",
  "Properties": [
    { "Key": "OverwriteExisting", "Value": "false" }
  ]
}

Error Handling

Condition	Result	Continues Workflow?
Key generated	Success (invisible)	Yes
Key already exists (OverwriteExisting=false)	Success (invisible, no change)	Yes
Invalid configuration	Success (uses defaults)	Yes

This step always succeeds and never blocks the workflow.

Best Practices

Key Length: Use at least 16 characters for adequate security
Character Set: Consider excluding ambiguous characters (0, O, l, 1) for keys that users might need to type
Overwrite: Set OverwriteExisting to false if you want keys to remain stable after generation
Notifications: Always use HTTPS when including secret keys in URLs
Expiration: Consider implementing time-based expiration in your application logic if needed

Set Custom Order Data - Store additional order metadata
Create Order Barcode - Generate barcodes for physical tracking

Order API - Get by Secret Key - API endpoint documentation
Notification Templates - Using ORDER_SECRET_KEY in emails