Collapse Menu
Documentation
FastSpring App
Contact Support

License Keys

Overview

FastSpring offers 6 ways for you to generate License Key fulfillments for your customers.

Table of Contents

By generating a License fulfillment, you can provide a license key (also known as a serial number, activation code, or product key) to consumers after a successful purchase. This can appear on the completion page following a successful purchase. Customers can also access their License Key in their email receipt, or their Account Management page.

Generate a License

  1. In the FastSpring App, navigate to the product’s details page. In the Fulfillments section, click Edit
  2. Click + Add Fulfillment > Generate a License
  3. Click Choose a Generator… to select the type of license generator. 
  4. Click Next

The following steps will vary depending on what type of license generator you selected.

Pre-Defined List 

If you have an existing list of pre-generated license keys, you can paste them in the Pre-Defined List field and control how many License Keys are issued per quantity purchased. After selecting this option within Choose a Generator, you can further customize the format and behavior of the Pre-Defined List.

  1. Below License Format, select whether you want to limit each Licence Key to a single line. If a single key can contain carriage returns, select Multi-Line License.
  2. Below License Quantity Behavior, select whether FastSpring issues a separate license key for each quantity purchased, or a single license key per purchase, regardless of the quantity.
  3. Below Step 2: Enter Licenses, enter a list of License Keys that follow the criteria you configured above. 
  4. Click Create. The License Configuration dialog displays the number of licenses available based on what you entered in the editor. 

Advanced Configuration

In the License List configuration page of each type of License Key, you can apply advanced configurations to customize your License Key.

  1. License Generator Name - Enter an internal-facing name for your license generator. 
  2. Ordered List - Select this checkbox to ensure FastSpring issues the License Keys in the order in which you pasted them. If you do not select this checkbox, FastSpring may issue license keys from your list in any sequence. 
  3. Custom Template Key - Enter an identifier to assign more than one license generator to the product. This enables you to separately identify them in a template, and use the identifier to control where the License Key is placed.

Script

You can supply a custom PHP script or JavaScript snippet for FastSpring to use when generating license keys. As you are applying changes, use the Test button at the top, right corner of the page to test your changes.

  1. From the Output Format drop-down, select the type of license key format that the script generates.
    • Single-Line License (Quantity Based) - The script generates one license key per quantity purchased. License keys generated by the script may be separated by a line feed character (or a carriage return + line feed character).
    • Multi-Line License (Quantity Based) - The script generates one license key per quantity purchased. However, license keys may be separated by an empty line. The empty line separator should only contain a line feed character (or a carriage return + line feed character).
    • Single License Only - The script generates one license key regardless of the quantity purchased by the customer. The license key may contain any type of character and may span multiple lines.
    • Single File Based License / MIME 1.0 - This advanced option supports binary data as a multipart/mixed MIME 1.0 file. Customers can download the file via a URL provided to them by FastSpring. 
  2. In the License Name field, click the drop-down selector and select which data point from the order details the script factors into license key generation.
    • Not Name Based - The license key generation does not take any name into consideration.
    • Email Address - The script bases the license keys on the customer's email address as entered during the purchase process.
    • Person Name - The script bases the license keys on the customer's full name as entered during the purchase process.
  3. In the Script Type drop-down, specify whether you are supplying a PHP script or a JavaScript snippet.
  4. Click Create. The General settings for your fulfillment are saved. You can edit the Output Format or License Name on the General page. 
  5. In the Script Source Code, enter the custom License Key Generation Code. 
  6. Save your changes. The script and configuration options get saved, and you are returned to the product or subscription detail page. The new fulfillment action License Generator (<type> Script) appears in the Fulfillment section of the product details page.

PHP Script Parameters

  • $name - The customer’s full name, company name, or email address, depending on License Name and the customer’s choice.
  • $name_unicode - Array of Unicode codepoints (integers) representing name.
  • $company - Customer’s company, if entered.
  • $company_unicode - Array of Unicode codepoints (integers) representing a company.
  • $email - Customer’s email address.
  • $quantity - It is the responsibility of the script to determine how quantity is handled. If you return multiple licenses, all licenses will be assigned to the order.
  • $product - The product name.
  • $reference - The order reference.
  • $subscription - The subscription ID.
  • $tags - Map of tag names to tag quantities. Tag names are defined at the product level and allow license generation to be based on other products in an order. Tag values are always 1 or greater.
  • $referrer - A custom value passed into the order process via the URL.

JavaScript Parameters

The following lists the order parameters and special functions available for use in your JavaScript code.
name - This may be the customer's full name, company name, or email address, depending on License Name and the customer's choice.

  • company - Customer's company, if entered.
  • email - Customer's email address.
  • quantity - It is the responsibility of the script to determine how quantity is handled. If you return multiple licenses, all licenses will be assigned to the order.
  • product - The product name.
  • reference - The order's reference / ID.
  • subscription - The subscription reference / ID.
  • tags - Map of tag names to tag quantities. Tag names are defined at the product level and allow license generation to be based on other products in an order. Tag values are always 1 or greater.
  • referrer - A custom value passed into the order process via the URL.

Special JavaScript Functions

  • sha1HexDigest(arg1) - arg1 is the String to produce the SHA1 hex digest for.
  • md5HexDigest(arg1) - arg1 is the String to produce the MD5 hex digest for.
  • aes(arg1,arg2) - arg1 is a 128 bit AES key in Base64. arg2 is the String to encrypt. Returns a Base64 String.
  • aesDecrypt(arg1,arg2) - arg1 is a 128-bit AES key in Base64. arg2 is the String to decrypt. Returns a Base64 String.
  • dsaSign(arg1,arg2) - arg1 is a 512 or 1024 byte DSA key in PEM format. arg2 is the String to sign. Returns a Base64 String.
  • base64(arg1) - arg1 is the String to convert to Base64. Returns a Base64 String.
  • base64Decode(arg1) - arg1 is the Base64-encoded String to decode. Returns a String.
  • rsaSha512Sign(arg1, arg2) - arg1 is the private key PEM, arg2 is the data to sign using SHA-512 with RSA. Returns the signature as a Base64 String.
  • httpGet(url, [params]) -
    var response = httpGet("http://www.example.com", 
    { "ipAddress": ipAddress } );
    response.statusCode;
    response.body;
  • httpPost(url, [params]) -
    var response = httpPost("http://www.example.com", { "ipAddress": ipAddress } );
    response.statusCode;
    response.body;
  • http({type:POST|GET, url: , username: , password:, params: {}}) -
    var response = http({
    type: "POST",
    url: "http://www.example.com",
    username: "tom",
    password: "secret",
    params: { "ipAddress": ipAddress }
    });
    response.statusCode;
    response.body;
To re-use this code or distinguish the License Keys it generates in the context of a template, go to the Advanced configuration page.

Remote Server Request

The Remote Server Request lets you configure a fulfillment action that contacts a remote server while the order is being processed to request a new, custom license key. When FastSpring receives the license key from the external server, we provide it to the consumer. This process also saves the license key as part of the completed order record.

  1. In the URL field, enter the URL or endpoint of your external server. FastSpring will access it during order processing to generate a license key. The URL must begin with http:// or https://.
  2. In the Method drop-down, select the POST or GET method for the HTTP request to your external server. We recommend using POST.
  3. If you selected POST, select the type of character encoding for the post body in the Post Encoding field below. 
    • This step does not apply for the GET method, as the URL includes the transaction data as URL parameters instead of transmitting the information as an HTTP message body. 
  4. In the Output Format drop-down, select the type of license format that FastSpring should expect from the remote server.
    • Single-Line License (Quantity Based) - The script generates one license key per quantity purchased. License keys generated by the script may be separated by a line feed character (or a carriage return + line feed character).
    • Multi-Line License (Quantity Based) - The script generates one license key per quantity purchased. However, license keys may be separated by an empty line. The empty line separator should only contain a line feed character (or a carriage return + line feed character).
    • Single License Only - The script generates one license key regardless of the quantity purchased by the customer. The license key may contain any type of character and may span multiple lines.
    • Single File Based License / MIME 1.0 - This advanced option supports binary data as a multipart/mixed MIME 1.0 file. Customers can download the file via a URL provided to them by FastSpring.
  5. Click Create

You can further customize the Remote Server Request License Configuration through the Security, Parameters, and Advanced configuration pages.

Security

The Security configuration page helps you secure the License Key generation process and prevent fraudulent requests from being accepted by your server. 

The Private Key field provides a unique, 32-character private key that you can use to verify the authenticity of requests originating from your FastSpring Store.


In the Authentication section of the page, specify a Username and Password for logging in. FastSpring passes the credentials specified here to the remote server with each license key generation request. You can optionally configure the script hosted by your server to ignore requests that don't include a valid login.

Parameters

The Parameters page provides a list of order parameters that you can include in the URL. FastSpring passes these data points, such as transaction details or customer data, to the remote server for use in license key generation. Some of the parameter names and values can even be customized to meet your needs, and you can configure up to ten additional custom parameters on this page as well.

Advanced

Optionally, apply advanced configurations listed below to customize your License Key.

  • License Generator Name - Enter an internal-facing name for your license generator. 
  • Ordered List - Select this checkbox to ensure FastSpring issues the License Keys in the order in which you pasted them. If you do not select this checkbox, FastSpring may issue license keys from your list in any sequence. 
  • Custom Template Key - Enter an identifier to assign more than one license generator to the product. This enables you to separately identify them in a template, and use the identifier to control where the License Key is placed.

CocoaFob

You can specify a DSA Private Key that is used for generating License Keys through CocoaFob. CocoaFob is an advanced option that may be beneficial for Mac or other Objective-C applications.

For more information, see: https://github.com/glebd/cocoafob
  1. In the Product Name field, enter the name of the product. This becomes part of the registration source string.
  2. In the DSA Private Key field, enter the private key used to generate licenses. The value you enter should begin with -----BEGIN DSA PRIVATE KEY----- and should end with -----END DSA PRIVATE KEY-----.
  3. Click Create.
  4. In the License Source Template field, specify the license source template used by your application to verify licenses.
  5. On the Advanced page, in the License Name field, click the drop-down and select which data point from the order details (if any) should be factored into license key generation.
    • Not Name Based - If the CocoaFob license key generation does not take any name into consideration, select this option.
    • Email Address - If the CocoaFob implementation bases the license keys on the customer's email address, as entered during the purchase process, select this option.
    • Person Name - If the CocoaFob implementation bases the license keys on the customer's full name, as entered during the purchase process, select this option. 
  6. Optionally, select the Generate Multiple Licenses checkbox for FastSpring to generate a separate license key for each quantity purchased in the order. If you do not select this checkbox, FastSpring generates one license key per product, regardless of the quantity purchased.
  7. In the Custom Template Key field, enter an identifier to assign more than one license generator to the product. This enables you to separately identify them in a template, and use the identifier to control where the License Key is placed.
  8. Save your changes. 

Aquatic Prime

Using AquaticPrime instructs FastSpring to generate a license file that is compatible with the third-party AquaticPrime algorithm.

For more information, see: https://github.com/bdrister/AquaticPrime.
  1. In the Product Name field, enter the name of the product to be used as the value for the "Product" key in the generated license file.
  2. In the Full License Filename field, enter the name of the downloadable license file to be provided to the customer, including the file extension. The file name may also contain the customer's name. For example, a final file name could be: "John Doe License.myapp".
  3. In the Public Key field, enter the public key for use in license key generation.
  4. In the Private Key field, enter the private key for use in validating license files generated using the public key.
  5. Click Create.
  6. The License Name field lets you select which data point from the order details (if any) should be used in the #{name} variable.
    • Not Name Based - If you select this option, the #{name} variable used in generating the license file is null.
    • Email Address - If the #{name} variable should contain the customer's email address, as entered during the purchase process, select this option.
    • Person Name - If the #{name} variable should contain the customer's full name, as entered during the purchase process, select this option
  7. Optionally, use the MIME Type field to override the default AquaticPrime file MIME type. 
  8. In the Content section, specify additional key/value pairs for inclusion in the license file output. In the Name column, enter the name of the key, and in the Value column, enter the corresponding parameter whose value is to be included in the license file (e.g., #{email}).
  9. Save your fulfillment. 

Advanced

  • License Generator Name - Enter an internal-facing name for your license generator.
  • Ordered List - Select this checkbox to ensure FastSpring issues the License Keys in the order in which you pasted them. If you do not select this checkbox, FastSpring may issue license keys from your list in any sequence. 
  • Custom Template Key - Enter an identifier to assign more than one license generator to the product. This enables you to separately identify them in a template, and use the identifier to control where the License Key is placed. 

Software Passport

If you are already using Software Passport to protect your application, you can enter your Software Passport project settings in order for FastSpring to generate License Keys compatible with your project. Contact Support for more information.

If your Software Passport implementation generates license keys based on the customer's name, and a customer enters the quotation mark (") as part of their name, the resulting license key will be invalid. We encourage you to advise buyers not to enter that character in the name fields, if possible.
  1. In the Encryption Template field, enter the encryption template from your Software Passport project for the current product.
  2. In the Signature Level field, click the drop-down and select the signature level used in your Software Passport project for the current product.
  3. In the Key Type / Version field, click the drop-down and select the key type and version used by your Software Passport project for the current product.
  4. Click Create. The General settings are saved, and an Advanced page becomes available.

Advanced

  1. The License Name field, on the Advanced tab, lets you select which data point from the order data. ils (if any) should be factored into license key generation via the name variable.
    • Not Name Based - If the license key generation does not take any name into consideration, select this option.
    • Email Address - If the license key generation bases the license keys on the customer's email address, as entered during the purchase process, select this option.
    • Person Name - If the license key generation bases the license keys on the customer's full name, as entered during the purchase process, select this option.
  2. In the License Name Modification field, indicate whether or not to modify the customer's license name, based on your selection above. 
  3. In the License Quantity Behavior field, select whether FastSpring issues a separate license key for each quantity purchased or a single license key per purchase, regardless of the quantity.
  4. Optionally, use the Custom Template Key field to enter an identifier to assign more than one license generator to the product. This enables you to separately identify them in a template, and use the identifier to control where the License Key is placed.
  5. Save your changes. The License Generator (SoftwarePassport) fulfillment appears in the Fulfillment section of the page.