Getting Started with Commercial API
Introduction
The WithSecure Commercial API offers a comprehensive set of endpoints exclusively for WithSecure™ partners operating in the Total Volume business model.
The WithSecure™ Commercial API is designed to fulfill the following use cases:
- Listing existing subscriptions.
- Automated provisioning of Total Volume usage or quantity-based subscriptions.
- Listing resellers (for distributors)
Total Volume business model
The WithSecure Commercial API enables our partners to automate commercial transactions using the WithSecure Total Volume business model.
In the Total Volume business model, all subscriptions are:
- Continuous until terminated
- Priced according to the frame agreement between WithSecure and the partner
- Invoiced monthly based on active subscriptions during the billing period
Total Volume subscriptions have two types:
- Usage-based — invoicing is based on the number of active assets during the month
- Quantity-based — invoicing is based on active order quantities during the month
To gain access to the WithSecure™ Commercial API, please contact the WithSecure™ Support Team or your WithSecure™ account manager.
Terminology
- Buyer - used to refer to a partner, for example, in ‘buyer_account_id’
- Service Partner (SEP) - Organization hierarchy where customer account is placed in Elements Security Center
- Licensees - used interchangeably with ‘companies’ and ’end-customers’
- Users - used to refer to administrators (admin users)
- EPP - Endpoint Protection
- EDR - Endpoint Detection and Response
Using the Commercial API
Our Commercial API is designed to provide full functionality for business transactions that are needed to provision and manage changes on WithSecure™ Total Volume subscriptions through the API. In other words, the API automatically creates and updates accounts for the licensees when needed. There is no need for a partner system that uses the API to have logic to manage the licensee account life cycle.
Business Transactions (Normal subscriptions)
| Business transaction | Endpoint to use | Notes |
|---|---|---|
| Provision a new subscription for a new licensee | Create new subscription | A licensee name together with an ID assigned, address and contact data will be used to create a new licensee account to provision first subscription for the licensee. |
| Provision a new subscription for an existing licensee | Create new subscription | An ID assigned to a licensee account with name, address and contact data can be used to provision additional subscriptions for the same licensee. |
| Increase a subscription quantity | Change subscription | Provide the “modify_subscription” object to set a new quantity. |
| Decrease a subscription quantity | Change subscription | Provide the “modify_subscription” object to set a new quantity. Note: New quantity must be greater or equal to the actual usage of the subscription. Any additional computers reserving licenses must be deleted in advance by using the WithSecure™ Elements Security Center or Elements API. |
| Upgrade a subscription product | Change subscription | Provide the “change_product” object to support upgrading, for example, from WithSecure™ Elements EPP for Computers to WithSecure™ Elements EPP for Computers Premium. The endpoints take the new product into use immediately. |
| Change a licensee name for the account | Create new subscription or Change subscription | Provide new name in the corresponding parameter to set a new name to a licensee account with specified assigned ID. |
| Grant a new admin user access to the portal | Create new subscription or Change subscription | Create an administrator account in the portal for managing the product. When you create a new account, the new administrator receives a welcome email. Note: Revoke access is not supported in the current version of API. |
| Listing subscriptions | Get subscriptions endpoints | Typically Partners retrieve subscription(s) for their invoicing purposes. |
| Terminate a subscription | Terminate subscription | Terminate subscription under a licensee. |
| Retrieve the subscription details | Get subscription by key | Retrieve the Total Volume subscription details for the specific subscription key, allowing partners to verify/check their subscriptions. |
| Retrieve subscriptions under a licensee | Get subscriptions by buyer assigned account Id | Used by Resellers to retrieve subscriptions details under a licensee by using partner’s buyer assigned account Id for the licensee, allowing partners to verify/check subscriptions for a licensee. |
| Retrieve subscriptions under a reseller | Get subscriptions by reseller account id | Retrieve the subscription details list under the specific reseller, allowing partners to verify/check subscriptions for resellers and licensees. To get list of Total Volume resellers Get Total Volume resellers endpoint should be used |
| Retrieve list of Total Volume resellers by Distributor | Get Total Volume Resellers | Used by Distributors to get list of Distributor Contracted Resellers with Total Volume Frame Agreement under specific Distributor. |
| Retrieve usage related to usage based subscriptions | Get Usage | API provide functionality to fetch aggregated Total Volume subscription usage information for billing purposes through API. Returns only usage related to usage based subscriptions, does not return information about quantity based subscriptions. |
Authentication and authorization
You must request access to the Commercial API from WithSecure™. We will provide you with separate system credentials together with business partner identifiers.
A partner system that calls the Commercial API needs to provide the given HTTPS credentials using a basic authentication scheme (RFC 7617) and initiating the HTTPS calls from allowed IP addresses. HTTPS credentials must match the allowed partner ID that defines the legal companies involved in the business transactions.
- licensee_party - identifies the end-customer company that will use the subscription
- buyer_account_id - identifies the partner’s legal company that uses the Commercial API
The WithSecure™ legal company that sells the subscription is linked to the partner ID and is managed within WithSecure™.
WithSecure™ provides the needed identifiers when the test and production environments have been created for you.
Supported products
Commercial API supports only Total Volume products.
As a partner, you can manage your customers Total Volume subscriptions. Create WithSecure Business Account for Elements Security Center access account for customers either through the Commercial API or Elements Security Center.
| Product | Commercial product name (EXTERNAL) | Allowed product changes to |
|---|---|---|
| W00163 | WithSecure™ Elements EPP for Computers | W00164, W00166 |
| W00164 | WithSecure™ Elements EPP for Computers Premium | W00166, W00163 |
| W00165 | WithSecure™ Elements EPP for Mobiles | - |
| W00166 | WithSecure™ Elements EDR and EPP for Computers Premium | W00163, W00164 |
| W00167 | WithSecure™ Elements EPP for Servers | W00168, W00169 |
| W00168 | WithSecure™ Elements EPP for Servers Premium | W00167, W00169 |
| W00169 | WithSecure™ Elements EDR and EPP for Servers Premium | W00167, W00168 |
| W00170 | WithSecure™ Elements Collaboration Protection | - |
| W00171 | WithSecure™ Elements EDR for Computers | W00163, W00164, W00166 |
| W00172 | WithSecure™ Elements EDR for Servers | W00167, W00168, W00169 |
| W00173 | WithSecure™ Elements Vulnerability Management | - |
| W00146 | WithSecure™ Elements Exposure Management Frontline Add-on | - |
| W00151 | WithSecure™ Elements MDR for Endpoints | - |
| W00152 | WithSecure™ Elements MDR for Identities | - |
| W00154 | WithSecure™ Elements Co-Monitoring Service Out of Office | - |
| W00155 | WithSecure™ Elements Co-Monitoring Service 24/7 | - |
Rollback
If there is a failure when you are creating a user or making changes to a subscription, the changes are rolled back.
Technical environments
For users with full-access, WithSecure™ provides two sets of system credentials: one for testing purposes and the other for production environments. This ensures that testing data remains separate from production data.
For users with read-only access, WithSecure™ only provides system credentials for the production environment.