Website Identity

Overview

WooNooW identifies each licensed website using two required values together:

persistent installation UUID + normalized domain

This combined identity is used for activation, validation, deactivation by identity, OAuth activation, and software update checks. Neither value is accepted as a fallback for the other.

Installation UUID

installation_id must be a canonical UUID using the 8-4-4-4-12 hexadecimal format:

550e8400-e29b-41d4-a716-446655440000

A client must:

1. generate it once using a cryptographically secure random UUID generator;
2. store it persistently for the installation;
3. reuse the same value for every license and update request within the same client integration scope;
4. keep that scope stable for the lifetime of the installation—the WooNooW reference updater scopes storage by store API URL + product slug;
5. avoid deriving it from the domain, license key, hardware, or personal data.

WordPress example:

$option_name    = 'my_product_installation_id';
$installation_id = strtolower(trim((string) get_option($option_name, '')));

if (!preg_match('/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/', $installation_id)) {
    $installation_id = wp_generate_uuid4();
    update_option($option_name, $installation_id, false);
}

Do not generate a new UUID on every request or routine plugin update. Losing the stored UUID causes the same domain to be treated as a different installation.

Domain normalization

Clients send the current site URL as domain for license operations and as site_url for update checks. WooNooW normalizes it by:

• removing the scheme, path, query, and fragment;
• lowercasing the hostname;
• removing a trailing dot;
• removing HTTP port 80 and HTTPS port 443;
• preserving non-default ports;
• treating www.example.com and example.com as different domains.

Send a canonical URL such as home_url() from WordPress. Authorization decisions use the server-normalized value.

Identity semantics

machine_id may be sent as optional metadata, but it does not form the canonical identity and cannot replace either required value.

Domain changes and migrations

A domain change creates a new identity even when the installation UUID remains unchanged. To release the old activation slot:

1. deactivate the old identity using its activation_id, or its old UUID + domain pair;
2. activate the same persistent UUID with the new domain;
3. continue using the new domain for validation and update checks.

If the old site is no longer accessible, the customer can deactivate it from My Account → Licenses when merchant settings allow deactivation.

Requests that require identity

The pair is mandatory on:

• POST /wp-json/woonoow/v1/licenses/activate;
• POST /wp-json/woonoow/v1/licenses/validate;
• POST /wp-json/woonoow/v1/licenses/deactivate when not using activation_id;
• OAuth activation requests and token exchange;
• GET|POST /wp-json/woonoow/v1/software/check.

See Licensing API, OAuth Activation Flow, and Software Updates API for complete request examples.