Activate License (Online Method)

19min
Activate a license for a product
POST
Request
Header Parameters
Date
required
String
In RFC7231 format (see "License API Authorization"), eg.: Thu, 17 Nov 2022 20:51:35 GMT
Authorization
required
String
See "License API Authorization" article
Body Parameters
hardware_id
required
String
Unique hardware ID generated for the client device
product
required
String
Product short code
license_key
optional
String
Required if product is key-based (see section below)
username
optional
String
Required if product is user based (see section below)
password
optional
String
Required if product is user based (see section below)
id_token
optional
String
Required if using SSO (see section below). This is the id_token received from the SSO if Implicit grant authorization method is being used.
code
optional
String
Required if using SSO (see section below). This is the code received from the SSO if Authorization code grant method is being used.
customer_account_code
optional
String
Required if using SSO (see section below). This is the customer_account_code to which SSO provider is configured. 
license_id
optional
Number
Ensures that the action affects only the license with the specified ID. This is useful if e.g. you have multiple licenses for the same product assigned to the same user. For obtaining a list of licenses assigned to a user, see "User Licenses"
is_vm
optional
Boolean
Set to true if using a virtual machine
vm_info
optional
String
Optional virtual machine metadata
os_ver
optional
String
Version of the operating system.
hostname
optional
String
Device hostname
os_hostname
optional
String
Hostname of the OS
ip
optional
String
IP address
ip_local
optional
String
Local IP address
app_ver
optional
String
Version of the product application used with this license
sdk_ver
optional
String
Version of the SDK used
mac_address
optional
String
Device MAC address
variables
optional
Object
Device variables. Variables are sent as a JSON object where the key is the variable name, and the value is the value of the variable
Curl
Node.js
JS
Python
Ruby
curl --location --request POST '/api/v4/activate_license' \
--header 'Accept: application/json' \
--header 'Date: string' \
--header 'Authorization: string' \
--data-raw '{"hardware_id":"String","product":"string","license_key":"string","username":"string","password":"string","id_token":"string","code":"string","customer_account_code":"string","is_vm":"Boolean","vm_info":"string","os_ver":"string","hostname":"string","os_hostname":"string","ip":"string","ip_local":"string","app_ver":"string","sdk_ver":"string","mac_address":"string"}'
curl --location --request POST '/api/v4/activate_license' \
--header 'Accept: application/json' \
--header 'Date: string' \
--header 'Authorization: string' \
--data-raw '{"hardware_id":"String","product":"string","license_key":"string","username":"string","password":"string","id_token":"string","code":"string","customer_account_code":"string","is_vm":"Boolean","vm_info":"string","os_ver":"string","hostname":"string","os_hostname":"string","ip":"string","ip_local":"string","app_ver":"string","sdk_ver":"string","mac_address":"string"}'
Responses
200
400
{
    "license_signature": "{license_signature_here}",
    "validity_period": null,
    "product_features": [
        {
      		"name": "feature 3",
            "code": "F3",
            "feature_type": "activation",
            "expiry_date": "2022-02-25"
        },
        {
            "name": "feature 4",
            "code": "F4",
            "feature_type": "consumption",
            "max_consumption": 10,
            "total_consumptions": 0,
          	"expiry_date": null
        }
    ],
    "license_type": "perpetual",
    "license_key": "1111-2222-3333-4444",
    "is_trial": false,
    "maintenance_period": null,
    "custom_fields": [
        {
            "name": "Field1",
            "data_type": null,
            "value": "default"
        }
    ],
    "max_activations": 1,
    "times_activated": 1,
    "customer": {
        "email": "[email protected]",
        "company_name": "",
        "reference": "",
        "phone": "",
        "first_name": "",
        "last_name": "",
        "customer_account": {
            "id": 20,
            "name": "LicenseSpring Inc.",
            "code": "licensespring_inc."
        }
    },
    "allow_overages": false,
    "max_overages": 0,
    "prevent_vm": false,
    "is_floating_cloud": false,
    "is_floating": false,
    "floating_timeout": 120,
    "transfer_count": 417,
    "max_transfers": 0,
    "start_date": null,
    "product_details": {
        "product_id": 1586066454418173,
        "product_name": "Acme App",
        "short_code": "XY",
        "authorization_method": "license-key"
    },
    "can_borrow": false,
    "max_borrow_time": 0,
    "device_id": 1642501399344530,
    "id": 1620711133620270
}
{
    "license_signature": "{license_signature_here}",
    "validity_period": null,
    "product_features": [
        {
      		"name": "feature 3",
            "code": "F3",
            "feature_type": "activation",
            "expiry_date": "2022-02-25"
        },
        {
            "name": "feature 4",
            "code": "F4",
            "feature_type": "consumption",
            "max_consumption": 10,
            "total_consumptions": 0,
          	"expiry_date": null
        }
    ],
    "license_type": "perpetual",
    "license_key": "1111-2222-3333-4444",
    "is_trial": false,
    "maintenance_period": null,
    "custom_fields": [
        {
            "name": "Field1",
            "data_type": null,
            "value": "default"
        }
    ],
    "max_activations": 1,
    "times_activated": 1,
    "customer": {
        "email": "test@example.com",
        "company_name": "",
        "reference": "",
        "phone": "",
        "first_name": "",
        "last_name": "",
        "customer_account": {
            "id": 20,
            "name": "LicenseSpring Inc.",
            "code": "licensespring_inc."
        }
    },
    "allow_overages": false,
    "max_overages": 0,
    "prevent_vm": false,
    "is_floating_cloud": false,
    "is_floating": false,
    "floating_timeout": 120,
    "transfer_count": 417,
    "max_transfers": 0,
    "start_date": null,
    "product_details": {
        "product_id": 1586066454418173,
        "product_name": "Acme App",
        "short_code": "XY",
        "authorization_method": "license-key"
    },
    "can_borrow": false,
    "max_borrow_time": 0,
    "device_id": 1642501399344530,
    "id": 1620711133620270
}
﻿
Schema
Request Body
TypeScript
JSON
type LicenseActivationRequestBody = ({

  // for key-based licenses:
  license_key: string

} | {

  // for user-based licenses, using username & password authentication:
  username: string
  password: string

} | {

  // for user-based licenses, using single sign-on Implicit grant authentication:
  id_token: string
  customer_account_code: string

} | {

  // for user-based licenses, using single sign-on Authorization code grant authentication:
  code: string
  customer_account_code: string

}) & {

  // required properties:
  hardware_id: string
  product: string

  // optional properties:
  bundle_code?: string | undefined
  license_id?: number | undefined
  is_vm?: boolean | undefined
  vm_info?: string | undefined
  os_ver?: string | undefined
  hostname?: string | undefined
  os_hostname?: string | undefined
  ip?: string | undefined
  ip_local?: string | undefined
  app_ver?: string | undefined
  sdk_ver?: string | undefined
  mac_address?: string | undefined
  variables?: { [key: string]: string } | undefined
}
type LicenseActivationRequestBody = ({

  // for key-based licenses:
  license_key: string

} | {

  // for user-based licenses, using username & password authentication:
  username: string
  password: string

} | {

  // for user-based licenses, using single sign-on Implicit grant authentication:
  id_token: string
  customer_account_code: string

} | {

  // for user-based licenses, using single sign-on Authorization code grant authentication:
  code: string
  customer_account_code: string

}) & {

  // required properties:
  hardware_id: string
  product: string

  // optional properties:
  bundle_code?: string | undefined
  license_id?: number | undefined
  is_vm?: boolean | undefined
  vm_info?: string | undefined
  os_ver?: string | undefined
  hostname?: string | undefined
  os_hostname?: string | undefined
  ip?: string | undefined
  ip_local?: string | undefined
  app_ver?: string | undefined
  sdk_ver?: string | undefined
  mac_address?: string | undefined
  variables?: { [key: string]: string } | undefined
}
﻿
Response Body
TypeScript
JSON
type LicenseActivationResponseBody = {
  id: number,
  allow_grace_period: boolean,
  allow_overages: boolean,
  allow_unlimited_activations: boolean,
  borrowed_until: string | null,
  can_borrow: boolean,
  channel: string,
  device_id: number,
  enable_maintenance_period: boolean
  environment: string,
  eula_link: string,
  floating_timeout: number,
  grace_period: number,
  hash_md5: string,
  installation_file: string,
  is_air_gapped: boolean,
  is_borrowed: boolean,
  is_expired: boolean,
  is_floating_cloud: boolean,
  is_floating: boolean,
  is_hardware_key_auth: boolean,
  license_active: boolean,
  license_enabled: boolean,
  license_signature: string,
  license_type: string,
  maintenance_period: string | null,
  max_activations: number,
  max_borrow_time: number,
  max_license_users: number,
  max_overages: number,
  max_transfers: number,
  order_store_id: string,
  prevent_vm: boolean,
  release_date: string,
  release_notes_link: string,
  requires_version: string,
  size: string,
  start_date: string | null,
  times_activated: number,
  transfer_count: number,
  validity_period: string | null, // string is in DateISO8601UTC format
  version: string,
  
  product_features: ({
    id: number,
    code: string,
    name: string,
    expiry_date: string,
    metadata: JSON,
    feature_type: 'activation' | 'consumption',
    is_floating: boolean,
    is_floating_cloud: boolean,

    // the following properties are only present if is_floating=true or is_floating_cloud=true
    floating_users: number,
    floating_timeout: number,

    // the following properties are only present if feature_type=consumption
    max_consumption: number,
    allow_unlimited_consumptions: boolean,
    total_consumptions: number,
    allow_overages: number,
    max_overages: number,
    reset_consumption: boolean,
    consumption_period: 'daily' | 'weekly' | 'monthly' | 'annualy' | null,
  })[],
  
  custom_fields: ({
    name: string,
    data_type: 'numer' | 'text' | 'date/time',
    value: string,
  })[],
  
  customer: {
    email: string,
    company_name: string,
    reference: string,
    phone: string,
    first_name: string,
    last_name: string,
    city: string,
    postcode: string,
    state: string,
    country: string,
    address: string,
    customer_account: string | null,
    metadata: JSON,
  },
  
  product_details: {
    product_id: number,
    product_name: string,
    short_code: string,
    authorization_method: 'license-key' | 'user',
    metadata: JSON,
  },
  
  metadata: JSON,
  
  // the following property is only present if is_trial=true
  trial_days: number,
  
  // the following properties is only present if is_floating=true or is_floating_cloud=true
  floating_in_use_devices: number,
  floating_users: number,
  
  // the following properties are only present if license_type='consumption'
  max_consumptions: number,
  total_consumptions: number,
  allow_unlimited_consumptions: boolean,
  reset_consumption: boolean,
  consumption_period: string | null, // string is in DateISO8601UTC format
  
} & ({

  // for key-based licenses:
  license_key: string,

} | {

  // for user-based licenses:
  user: {
    id: number,
    email: string,
    first_name: string,
    last_name: string,
    phone_number: string,
    is_initial_password: boolean,
    max_activations: number,
    allow_unlimited_activations: boolean,
    total_activations: number
  }
});

type LicenseActivationResponseBody = {
  id: number,
  allow_grace_period: boolean,
  allow_overages: boolean,
  allow_unlimited_activations: boolean,
  borrowed_until: string | null,
  can_borrow: boolean,
  channel: string,
  device_id: number,
  enable_maintenance_period: boolean
  environment: string,
  eula_link: string,
  floating_timeout: number,
  grace_period: number,
  hash_md5: string,
  installation_file: string,
  is_air_gapped: boolean,
  is_borrowed: boolean,
  is_expired: boolean,
  is_floating_cloud: boolean,
  is_floating: boolean,
  is_hardware_key_auth: boolean,
  license_active: boolean,
  license_enabled: boolean,
  license_signature: string,
  license_type: string,
  maintenance_period: string | null,
  max_activations: number,
  max_borrow_time: number,
  max_license_users: number,
  max_overages: number,
  max_transfers: number,
  order_store_id: string,
  prevent_vm: boolean,
  release_date: string,
  release_notes_link: string,
  requires_version: string,
  size: string,
  start_date: string | null,
  times_activated: number,
  transfer_count: number,
  validity_period: string | null, // string is in DateISO8601UTC format
  version: string,
  
  product_features: ({
    id: number,
    code: string,
    name: string,
    expiry_date: string,
    metadata: JSON,
    feature_type: 'activation' | 'consumption',
    is_floating: boolean,
    is_floating_cloud: boolean,

    // the following properties are only present if is_floating=true or is_floating_cloud=true
    floating_users: number,
    floating_timeout: number,

    // the following properties are only present if feature_type=consumption
    max_consumption: number,
    allow_unlimited_consumptions: boolean,
    total_consumptions: number,
    allow_overages: number,
    max_overages: number,
    reset_consumption: boolean,
    consumption_period: 'daily' | 'weekly' | 'monthly' | 'annualy' | null,
  })[],
  
  custom_fields: ({
    name: string,
    data_type: 'numer' | 'text' | 'date/time',
    value: string,
  })[],
  
  customer: {
    email: string,
    company_name: string,
    reference: string,
    phone: string,
    first_name: string,
    last_name: string,
    city: string,
    postcode: string,
    state: string,
    country: string,
    address: string,
    customer_account: string | null,
    metadata: JSON,
  },
  
  product_details: {
    product_id: number,
    product_name: string,
    short_code: string,
    authorization_method: 'license-key' | 'user',
    metadata: JSON,
  },
  
  metadata: JSON,
  
  // the following property is only present if is_trial=true
  trial_days: number,
  
  // the following properties is only present if is_floating=true or is_floating_cloud=true
  floating_in_use_devices: number,
  floating_users: number,
  
  // the following properties are only present if license_type='consumption'
  max_consumptions: number,
  total_consumptions: number,
  allow_unlimited_consumptions: boolean,
  reset_consumption: boolean,
  consumption_period: string | null, // string is in DateISO8601UTC format
  
} & ({

  // for key-based licenses:
  license_key: string,

} | {

  // for user-based licenses:
  user: {
    id: number,
    email: string,
    first_name: string,
    last_name: string,
    phone_number: string,
    is_initial_password: boolean,
    max_activations: number,
    allow_unlimited_activations: boolean,
    total_activations: number
  }
});
﻿
Response Signature
The response objects contains a license_signature value which the client app can use to verify the authenticty of the response (see the Response Signature﻿ article for instructions on how to verify this signature).
License Authorization Method
There are two types of product licenses based on how the client application authorizes itself to interact with a license:
Key-based product licenses
Each license assigned to the product requires the client to provide a license key in order to activate, check or deactivate the license (property license_key in the request body).
The license response object will contain the license_key property, and the property product_details.authorization_method will be the string license_key.
User-based product licenses
Each license assigned to the product has a corresponding "license user" instead of a license key. There are multiple ways a user-based product license can be accessed when making a request:
By providing the values for username and password for the license user
By providing the values for id_token and customer_account_code if using single sign-on authentication using Implicit grant
By providing the values for code and customer_account_code if using single sign-on authentication using Authorization code grant
﻿
In the license response object, product_details.authorization_method will have the string value user and the response object will contain the user object with information on the license user. 
License Types
The license_type property defines one of the 4 types of licenses based on their duration and how the license is used:
Perpetual: perpetual
Time-limited: time-limited
Subscription: subscription
Consumption: consumption
For more information see: License Types﻿ 
Errors
If an error occurs, the response will have an HTTP status code of 400 or higher, and the response body will contain an error description in the following format:
TypeScript
{
  status: number,
  code: string,
  message: string
}
{
  status: number,
  code: string,
  message: string
}
﻿
List of exceptions
unknown_product (400): Provided product was not found
license_not_found (400): License with the provided license user not found
license_not_enabled (400): The license is not enabled
vm_not_allowed (400): Virtual machine not allowed
offline_floating_cloud_not_supported (400): Floating cloud licenses cannot be activated offline
license_start_date_error (400): This license cannot be activated before start date: {date}
blacklisted (400): This device is blacklisted
license_activated_max_times (400): This license key has already been activated the maximum number of times
license_user_activated_max_times (400): License user has activated this license max times
license_expired (400): License validity period has expired
license_transferred_max_times (400): This license has already been transferred the maximum number of times
license_device_exists (409): A device matching this hardware_id is already created on the license.
Examples
User-Based License Activation
Curl
curl --location --request POST 'https://api.licensespring.com/api/v4/activate_license/' \
--header 'Date: Mon, 10 May 2021 13:14:18 GMT' \
--header 'Authorization: algorithm="hmac-sha256",headers="date",signature="{generated_signature}",apikey="{your_api_key}"' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "[email protected]",
    "password": "some_password123",
    "hardware_id": "some-unique-id",
    "product": "XY"
}'
curl --location --request POST 'https://api.licensespring.com/api/v4/activate_license/' \
--header 'Date: Mon, 10 May 2021 13:14:18 GMT' \
--header 'Authorization: algorithm="hmac-sha256",headers="date",signature="{generated_signature}",apikey="{your_api_key}"' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "test@example.com",
    "password": "some_password123",
    "hardware_id": "some-unique-id",
    "product": "XY"
}'
﻿
Single-Sign-On License Activation
Short instructions and link to detailed section about using Single Sign On directly via License Api can be find here﻿ 
Curl
curl --location --request POST 'https://api.licensespring.com/api/v4/activate_license/' \
--header 'Date: Mon, 10 May 2021 13:14:18 GMT' \
--header 'Authorization: algorithm="hmac-sha256",headers="date",signature="{generated_signature}",apikey="{your_api_key}"' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id_token": "{id_token_here_}",
  	"code": "{code_here}",
    "customer_account_code": "acme_inc",
    "hardware_id": "some-unique-id",
    "product": "XY"
}'
curl --location --request POST 'https://api.licensespring.com/api/v4/activate_license/' \
--header 'Date: Mon, 10 May 2021 13:14:18 GMT' \
--header 'Authorization: algorithm="hmac-sha256",headers="date",signature="{generated_signature}",apikey="{your_api_key}"' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id_token": "{id_token_here_}",
  	"code": "{code_here}",
    "customer_account_code": "acme_inc",
    "hardware_id": "some-unique-id",
    "product": "XY"
}'
﻿
Use either id_token or code, not both at the same time.
Device variables
The optional variables property lets you set device variables during activation. For more information on how device variables work, see Device Variables﻿﻿
Updated 17 Jan 2025
Did this page help you?
License Activation/Deactivation
Deactivate License (Online Method)