Licenses

Information about setting up the components of the Licenses feature, adding and managing licenses, assigning license terms and scopes to a license, and assigning licenses to APIs.

Note: For an overview of the Licenses feature, with implementation scenarios and examples, see Licenses: Feature Overview. For information about scopes, see Scopes.

What is a license?
What is a license term?
What are the visibility rules for a license?
How do I add a license?
How do I edit a license?
How do I deactivate or reactivate a license?
How do I delete a license?
How do I add a policy to a license?
How do I modify a policy?
How do I delete a policy?
How do I assign a license to an API?

What is a license?

A license is a tailored API access package designed by the Business Admin/API Admin and offered to the app developer. A license includes:

One or more License Terms, each of which can include multiple scopes, giving access to specifically designated operations, and multiple quality of service (QoS) agreements.
One or more legal agreements applicable to the license.

API visibility is controlled at the license level and also at the Scope level. This means that the license feature can be used not only to package an API for the purposes of monetization, development, or for any other reason, but also to control visibility so that only members of designated user groups can even see portions of the API (and the associated documentation). API access is granted at the license level.

Defining a License:

Business Administrators can define a license in the More > Admin >Licenses section using the +Add License function. As a prerequisite to defining a license you must have scopes pre-defined. Scopes are part of the license definition.

Some points to note when defining a license:

It's best to define scopes first. You can define a license without adding Scopes, but a license is meaningless without at least one scope assigned to it.
As part of the license, you must define one or more license terms.
One or more Scopes can be assigned a license using the Add Scope function.
Each Scope can be tailored using the Select Scope function (you can select or deselect specific tiers within the Scope).
After you save the license, the API Admin must specify that the API uses licenses, and must map scopes to operations within the API (scope mapping). If the license is private, the API Admin must also create an API Scope Group or invite other groups to access the API and specify that the groups have access to that license. Once those steps are complete, applicable licenses are available for app developers to select in the API Access Wizard.

What is a license term?

A license term is a building block for a license. A license is made up of one or more license terms plus, optionally, one or more legal agreements. When defining a license, you define one or more license terms. Each license term is unique to the license that it is a part of; license terms do not exist separately from licenses.

A license term includes two components:

The access that is being offered in terms of what exactly the user is being given access to (scope); for example, access to read-only operations, access to credit card operations, access to all operations.
The level of access in terms of quality of service and/or volume of transactions (QoS policy).

Each license term includes one or more scopes plus, optionally, the quality of service limits/policies to be applied to all scopes in the license term. Scopes apply to both visibility and access; policies apply only to access. To have any impact, a license term must include at least one scope.

What are the visibility rules for a license?

The following visibility rules apply for a license:

Public licenses are always available for selection in the API Access Request wizard.
Private licenses are only visible to an app developer if the developer's visibility scope for an API version includes that license. This happens when a group that the developer is a member of has access to the license.
A public API can have a private license. In this scenario, all users see the parts of the API that are not included in the private license. The operations that are in the private license, and their corresponding documentation, are only visible to users who have explicit access to all scopes within that license.

How do I add a license?

You can configure a license using the Add License function in the More > Admin >Licenses section of the platform:

Scopes must be predefined in the More > Admin >Scopes section so that they are available for selection when defining the license.
Quality of Service (QoS) policies must be defined in Policy Manager.
The process of configuring a license involves assigning a name and description, configuring the approval level for Sandbox and Live Access (Auto Approved or Approval Required), setting Visibility (Public or Private), and defining one or more license terms, each of which includes one or more scopes and QoS policies that will apply to the license (in the More > Admin >Licenses section).
You can upload legal agreements during the license creation process.
The Add Term function allows you to add a license term. A license can include multiple terms, each of which can include one or more scopes and QoS policies.
The Delete function allows you to delete a license definition line item.

Note: Licenses can only be configured by Business Administrators.

To add a license

Log in to the Community Manager developer portal as the Business Admin.
Go to More > Admin >Licenses.

On the Licenses page, click Add License. Specify the Name, Description, Visibility (Public/Private), and Sandbox Access and Live Access options you would like to assign to the license definition.

Item	Description
Name	Specify the license name. The license name will display in the API Access Wizard when an app is requesting access to an API.
Description	Specify a short description for the license. The app developer sees this at runtime when requesting a contract with an API that uses the license feature, as shown below.
Implementation	Check one or more boxes for the implementations the license will apply to. Checking a specific box enables the applicable section below.
Visibility	Select a Visibility option. The following rules apply: Public: A public license is visible to app developers when requesting API access for an app. If there is documentation or downloadable content for a public API's licenses, scopes, or operations that are designated with a visibility of public, those resources are visible to all users. If the API itself is private but the scope is public, the resources are visible to all users who have been invited to the API. Private: A private license is visible only to an app developer who is a member of one or more groups invited to have visibility of the license. If an app developer's visibility scope for an API version includes a private license, that developer will have the option to choose that license when requesting API access. If a license is private, only users that have the license in their visibility scope can access the API documentation/downloadable files that are mapped to the license. Note: The API admin must make sure that the documentation is appropriately tagged. If it is not, it will not be visible even to authorized individuals. For information on tagging API documentation, see How do I control visibility of API documentation files?
Sandbox Access	Available only if Sandbox is checked in the Implementation field. This setting determines whether API access requests for the sandbox environment are granted automatically or require API Admin approval. If the API is set to auto approval, access is always automatic. If the API is set to manual approval, the setting for the license is used. Choose from the following: Auto Approval: If an app requests Sandbox API access for one or more licenses all of which are set to Sandbox Access >Auto Approved, the API access request is auto approved. Approval Required: If any one of the licenses is set to Sandbox Access > Auto Approved, the API access request is placed in a Pending Approval state until approved by the API Admin.
Live Access	Available only if Live is checked in the Implementation field. This setting determines whether API access requests for the Live implementation are granted automatically or require API Admin approval. If the API is set to auto approval, access is always automatic. If the API is set to manual approval, the setting for the license is used. Choose from the following: Auto Approval: If an app requests API access to the Live implementation for one or more licenses all of which are set to Live Access Auto Approved, the API access request is auto approved. Approval Required: If any one of the licenses is set to Approval Required, the whole API access request will be placed in Pending Approval state.

Click Next. The Terms page displays. Here you will define one or more license terms that comprise the license.
Click Add Term. The Add Term dialog displays. Choose one or more Scopes and one or more QoS policies that will be included in the license term.
Click Finish. The license term is added to the license.
Define additional terms if needed and then click Next.
Choose one or more legal agreements that will apply to the license. If needed, you can add or upload a new legal agreement:
- If necessary, first upload the file: click Upload Legal.
- Add the legal document to the license: click Add Legal and define display name and description, and click Save.
Click Finish.

Once the license is defined, the API Admin or Business Admin can apply the license to the API. The steps are:

Make sure the API is using licenses (License check box checked in the API definition).
Map operations to scopes (scope mapping option from the API page).
If the API is private, create an API Scope Group or invite existing groups to have visibility of the API.
If the license is private, specifically invite groups to have visibility of those licenses.

Once those steps are complete, the license will be available to app developers when making an API access request.

How do I edit a license?

You can modify a license, if it is deactivated, using the Edit function in the More > Admin >Licenses section of the platform.

Note: When a license is active you cannot modify it.

To edit a license

Log in to the Community Manager developer portal as the Business Admin.
Go to More > Admin >Licenses.
On the Licenses page, in the left panel, select the license Parent or Child you would like to edit, and click Edit in the right panel. Change the values as needed. For explanations of the fields and their values, refer to To add a license.
Click Next. The Scopes page displays. Here you can modify the existing Scope Definition or add a new Scope definition.
To modify an existing Scope Definition, click Select. The Select Scope popup displays. Update as needed.
To add a new Scope Definition, click Add Scope, and then click Select. The Select Scope popup displays. Click the check box for each Scope you would like to add to the license definition. Click Confirm to save your changes.
Click Save. The modified license is now available for selection in the API Access Wizard.

How do I deactivate or reactivate a license?

You can deactivate a license definition on the License Definitions page. Note:

When you deactivate a license it still exists on the License Definitions page, but is not available for selection on the Licenses page in the API Access Wizard.
You can edit the license when it is deactivated.
You cannot deactivate a license if it is in use in a current API access request or contract. You must first cancel any pending or approved API Access Requests.

To deactivate a license

Log in to the Community Manager developer portal as the Business Admin.
Go to More > Admin >Licenses.
On the Licenses page, find the license you want to deactivate, and click the license name to go to the license details page.
Click Deactivate. The license is deactivated.

To reactivate a license

Log in to the Community Manager developer portal as the Business Admin.
Go to More > Admin >Licenses.
On the Licenses page, find the license you want to reactivate, and click the license name to go to the license details page.
Click Activate. The license is reactivated.

How do I delete a license?

You can delete a license on the License Definitions page:

You cannot delete a License if it is in use (that is, if it was selected as part of an API Access Request). You must first cancel any pending or approved API Access Requests.

To delete a license

Log in to the Community Manager developer portal as the Business Admin.
Go to More > Admin >Licenses.
On the Licenses page, find the license you want to delete, and click the license name to go to the Details page for the license.
In the license details page, click Delete. Click OK to confirm.

How do I add a policy to a license?

The Licenses feature uses policies as a component when building the license definition; policies are an optional component in license terms. However, policies are defined outside the platform, in Policy Manager.

As soon as the policy is defined in the API Gateway, it is available for selection when you go to More > Admin >Licenses, click Add License, and add a license term to the license.

If you want to create licenses but the policies are not set up yet, you can go ahead and set up the licenses without the policies, and then go back and add the policies when they're available.

How do I modify a policy?

You can modify a policy by changing the policy definition in Policy Manager.

How do I delete a policy?

If you want to delete a policy, it must be done in Policy Manager, where the policies are set up. Note that you can only delete a policy that is not in use.

You cannot delete a policy if:

There is a license definition that references the policy.
There is an active or pending API access contract that references the policy.

How do I assign a license to an API?

The API Admin or Business Admin links license definitions to an API by completing the following steps:

In the API setup, making sure the Choose Licenses check box is selected.
From the API page, assigning scopes to the API (scope mapping).

Once those steps are complete, any licenses that include those scopes in the license definition are presented to the app developer for selection when the app developer initiates an API access request.