Business Administration

Licenses

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

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

What is a license?
What is a license term?
What are the visibility rules for a license?
What is a scope?
How do I add a scope?
How do I modify a scope?
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?
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 Administration > Licenses section using the +Add License function. As a prerequisite to defining a license you must have scopes pre-defined (via the Administration > Scopes section) as scopes are a component 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 a Private API 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.

What is a scope?

A scope is the bridge between the top level of the hierarchy, a license, and the bottom level, an operation. At the business level, the Business Admin defines the scope with a name and basic attributes. Then, at the API level, the API Admin assigns specific operations to one or more scopes for the API. These operations are included in any license that the scope is assigned to.

The app developer never sees scopes; the developer is offered one or more licenses offerings that have been defined for the API. However, scopes are a building block of licenses.

Operations are assigned to scopes; scopes and QoS policies are assigned to license terms; license terms and legal agreements are assigned to licenses.

How do I add a scope?

You can configure a scope using the Add Scope function in the Administration > Scopes section of the platform. Some things to note about scopes:

The only required fields are Name and Short Description. You can also add a more detailed description in the Full Description field.
Specify the visibility. A public license is visible to app developers when requesting API access for an app.
Choose whether anonymous access will be allowed to your Sandbox or Production environments (not recommended)
If you are using OAuth you can also specify whether the scope should be included in the OAuth default scope (used if no scopes are specified in the request) and whether user authorization is required.
The Delete function allows you to delete a scope.

You can also:

Edit a scope. Highlight the scope and then, in the right pane, click Edit.
Add a child scope. Highlight the scope and then, in the right pane, click Add Child. You can define multiple levels of scope hierarchy.
Delete a scope. Highlight the scope and then, in the right pane, click Delete.

Note: Scopes can only be configured by Business Administrators.

To add a scope:

Navigate to Site Administration > Licenses. The Scopes screen displays.
Click Add Scope. In the right panel, specify the following:
- Name (required)
- Short Description (required)
- Full Description
- Visibility: When a scope has public visibility, anything mapped to the scope (operations or documents) is visible to all users including anonymous users. Private visibility implies that anything mapped to this scope is visible to users that have the same visibility scope granted to them, based on API invitations to one or more groups that the user is a member of.
- Anonymous access: If anonymous access is allowed for a scope, operations that are mapped to the scope can be used by apps that do not identify themselves to the gateway with any credentials. The app does not even need to be registered in the platform. We recommend not allowing anonymous access to your API. For more information, see What is Anonymous API Access?
If you are using OAuth, specify the two OAuth values:
- Default Scope: If OAuth is being used and an app's grant access request does not specify scopes, all scopes that have the Default scope option checked are included in the scope of the grant.
- User Authorization Required: If the scope is being used for OAuth, user authorization is required for scope access. If an OAuth grant includes all scopes with this option disabled, the provider does not require the resource owner to authorize the grant request.
Click Save. The scope is now available for selection when creating a license.

How do I modify a scope?

You can modify a scope using the Edit function in the Administration > Scopes section of the platform.

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

To edit a scope:

Navigate to Site Administration > Scopes. The Scopes screen displays.
In the left panel, select the scope you want 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 scope. There are also explanations of key fields on the page itself (available on hover).
Click Save. The modified scope is now available for selection when creating a license.

How do I add a license?

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

Scopes must be predefined in the Administration > 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 Production 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 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

Navigate to Site Administration > Licenses. The Licenses screen displays.

Click Add License. Specify the Name, Description, Visibility (Public/Private), and Sandbox Access and Production 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, as shown below.
Sandbox Access	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.
Production Access	This setting determines whether API access requests for the production 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 production API access for one or more licenses all of which are set to Production 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.
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 into the license (visibility scope). 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?

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 overlay 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.
When done, click Finish. The license is saved.

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 checkbox checked in the API definition).
Map operations to scopes (scope mapping option from the API page).
If the API is private, create a Private API Group or invite existing groups to have visibility into 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 Administration > License section of the platform.

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

To edit a license:

Navigate to Site Administration > Licenses. The Licenses screen displays.
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 checkbox 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 screen using the Deactivate function. Note the following points:

When you deactivate a license it still exists on the License Definitions screen, 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:

Navigate to Site Administration > Licenses. The licenses list displays.
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:

Navigate to Site Administration > Licenses. The licenses list displays.
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 screen using the Delete function:

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

To delete a license:

Navigate to Site Administration > Licenses. The licenses list displays.
Find the license you want to delete, and click the license name to go to the license details page.
In the license details page, click Delete. Click OK to confirm.

How do I add a policy?

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 click Add License ( Administration > Licenses) 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 checkbox 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.