Getting Started with Provisioning API
Introduction
The WithSecure™ Provisioning API is designed to fulfill the following use cases:
- Listing WithSecure subscriptions.
- Managing bundles of subscriptions for the usage-based security (UBS) business model.
Please note that the Provisioning API, in read-only mode, only supports the ability to list subscriptions.
However, with the Provisioning API, you not only have the ability to create and modify subscriptions but also create companies (“licensees”), resellers (“Service Partners”), and users (“admin users”) for the security portals.
To gain access to the Provisioning API, kindly reach out to the WithSecure™ Support team or your dedicated WithSecure™ account manager.
Terminology
- Buyer - used to refer to a partner, for example, in ‘buyer_account_id’
- Service Partner (SEP) - used interchangeably with ‘reseller’
- 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 Provisioning API
Our Provisioning API is designed to provide full functionality for business transactions that are needed to provision and manage changes on WithSecure™ 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.
The Provisioning API supports bundle subscriptions that contain multiple subscriptions that are activated and terminated together.
The Provisioning API handles changes to the bundle structure automatically. If individual subscriptions are added to or deleted from the bundle, the changes for each licensee are made automatically without any action required from the partner system.
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 to a licensee account can be used to provision additional subscriptions for the same licensee. |
| Provision a new subscription for an existing licensee | Create new subscription | A licensee name together with an ID assigned to a licensee account can be used to provision additional subscriptions for the same licensee. |
| Extend a subscription expiration | Change subscription | Provide the “modify_subscription” object. |
| 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: The new quantity must be greater than or equal to the actual use of the subscription. Using the WithSecure™ Elements EPP portal or the Management API, you must delete in advance any additional computers that reserve licenses. |
| 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 EDR and EPP for Computers Premium. The endpoints take the new product into use immediately. |
| Downgrade a subscription product | Change subscription | Provide the “change_product” object to support downgrading, for example, from WithSecure™ Elements EDR and EPP for Computers Premium to WithSecure™ Elements EPP for Computers. The endpoints take the new product into use immediately. |
| Change a licensee name or the ID for the account assigned by a partner | Change subscription | Provide the “change_licensee_party” object to set a new name or an ID assigned to a licensee account. |
| Deactivate a subscription | Change subscription | Provide the “modify_subscription” object with an expiration set to “expire” and an expiration_date set to the current or a future date. |
| Reactivate an expired subscription | Change subscription | Provide one of the following for “modify_subscription” object: Set “expiration” to “expire” and “expiration_date” to a future date, or set “expiration” to “continuous”. Note: A clean-up routine will remove the subscription four months after the expiry date, after which a reactivation will fail. |
| 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. |
| Revoke portal access for an existing admin user | Change subscription | Delete an administrator account from the portal. Note: You cannot revoke an administrator account at the same time as you are granting access to a new administrator. |
| Move a subscription to another licensee | Move subscription | Provide the subscription key to move the subscription another (existing) licensee. |
| Listing subscriptions | Get subscriptions endpoint | Typically Partners retrieve subscription(s) for their invoicing purposes. |
| Delete a subscription | Terminate subscription | Remove subscription under a licensee. |
| Register and grant access to a new SEP | Create SEP | SEPs can enable second-tier management of the licensee subscriptions, allowing partners to manage their own subscriptions. |
| Retrieve the subscription details | Get subscription by key | Retrieve the subscription details for the specific license key, allowing partners to verify/check their own subscriptions. |
| Retrieve subscriptions under a licensee | Get subscriptions by company uuid or Get subscriptions by reference number | Retrieve the subscription details list under the specific licensee, allowing partners to verify/check subscriptions for a licensee. |
| Retrieve subscriptions under a partner | Get subscriptions by partner uuid or Get subscriptions by buyer account id | Retrieve the subscription details list under the specific partner, allowing partners to verify/check subscriptions for resellers and licensees. |
| Change a SEP name | Update SEP | Provide the SEP unique identifier to set a new SEP name. |
| Relocate a licensee | Move company | Move an existing licensee under same buyer to another existing service partner. |
| Delete a licensee | - | Any unnecessary licensee data will be removed automatically if no subscriptions are left. |
Business Transactions (Subscription bundles)
| Business transaction | Endpoint to use | Notes |
|---|---|---|
| Provision a new subscription bundle for a new licensee | Create new bundle | The ID assigned to a licensee account is needed to provision additional subscriptions. |
| Provision a new subscription for an existing licensee | Create new bundle | The ID assigned to a licensee account is needed to provision additional subscriptions. |
| Deactivate a bundle subscription | Terminate bundle | Set “expiration_date” to the current date or to a future date. |
Authentication and authorization
You must request access to the Provisioning API from WithSecure™. We will provide you with separate system credentials together with business partner identifiers.
A partner system that calls the Provisioning 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 Provisioning 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
The product code comprises the first four characters of the product SKU.
Provisioning API supports only partner-managed products.
As a partner, you can manage any partner-managed products either fully or jointly. You provision partner-managed subscriptions under your Business Account. By default, licensees do not have access to any portal unless you create an admin account for the licensee either through the Provisioning API or one of the WithSecure™ product portals.
| Product | Commercial product name (EXTERNAL) | Allowed product changes to | Access to product portals |
|---|---|---|---|
| FCXC | WithSecure™ Elements EPP for Computers | FCXX, FCED | WithSecure™ Elements Security Center - Endpoint Protection (EPP) |
| FCXX | WithSecure™ Elements EPP for Computers Premium | FCED, FCXC | WithSecure™ Elements Security Center - Endpoint Protection (EPP) |
| FCDA | WithSecure™ Elements EPP for Mobiles | - | WithSecure™ Elements Security Center - Endpoint Protection (EPP) |
| FCED | WithSecure™ Elements EDR and EPP for Computers Premium | FCXC, FCXX | WithSecure™ Elements Security Center - Endpoint Protection (EPP) and Endpoint Detection and Response (EDR) |
| FCXG | WithSecure™ Elements EPP for Servers | FCRF, FCRB | WithSecure™ Elements Security Center - Endpoint Protection (EPP) |
| FCRF | WithSecure™ Elements EPP for Servers Premium | FCXG, FCRB | WithSecure™ Elements Security Center - Endpoint Protection (EPP) |
| FCRB | WithSecure™ Elements EDR and EPP for Servers Premium | FCXG, FCRF | WithSecure™ Elements Security Center - Endpoint Protection (EPP) and Endpoint Detection and Response (EDR) |
| FCVI | WithSecure™ Elements Collaboration Protection | - | WithSecure™ Elements Security Center - Collaboration Protection |
| FCEA | WithSecure™ Elements EDR for Computers | FCXC, FCXX, FCED | WithSecure™ Elements Security Center - Endpoint Protection (EPP), Endpoint Detection and Response (EDR) |
| FCEN | WithSecure™ Elements EDR for Servers | FCXG, FCRF, FCRB | WithSecure™ Elements Security Center - Endpoint Protection (EPP), Endpoint Detection and Response (EDR) |
| FCKC | WithSecure™ Elements Vulnerability Management | - | WithSecure™ Elements Security Center - Vulnerability Management |
| FCDB | WithSecure™ Elements EPP for Mobiles (without VPN) | - | WithSecure™ Elements Security Center - Endpoint Protection (EPP) |
| FCYV | WithSecure™ Elements Identity Security for Entra ID | - | WithSecure™ Elements Security Center - Endpoint Protection (EPP) |
| FCYY | WithSecure™ Elements Exposure Management for Business | - | WithSecure™ Elements Security Center - Exposure Management |
Subscription bundles (usage-based security)
| Product | Commercial product name (EXTERNAL) | Allowed product changes to | Access to product portals |
|---|---|---|---|
| FCZA | WithSecure™ Elements Usage-Based Security | - | WithSecure™ Elements Security Center - Endpoint Protection (EPP), Endpoint Detection and Response (EDR) and Collaboration Protection |
Rollback
If there is a failure when you are creating a user or making changes to a subscription, the changes are rolled back. However, there will be no rollback if creating or updating a licensee fails.
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.