API Licenses and Scopes

Configure license scopes to determine what features of the API will be offered with different licenses.

Table of Contents

How do I determine what licenses will be available for my API?

There are a couple of steps you'll need to complete to define the licenses that app developers will see when requesting access to your API. On the API Details page, from the drop-down list at the top right, choose Manage Licensing.

The scopes are the link between your API and the licenses that are offered to app developers. The Business Admin defines the licenses and scopes, and you assign the scopes to your API with either API-wide mapping or operation-specific mapping. If you have any questions about which scopes to assign or which licenses will be available, consult your Business Admin.

For an overview of the Licenses feature and the relationship between the setup steps performed by the Business Admin and those done by the API Admin, and the relationship between scopes and licenses, see Licenses: Feature Overview.

What is scope mapping and how do I set it up?

If your API is using the Licenses feature, scope mapping is the key to defining which portions of your API will be available for which licenses. The scopes and licenses themselves are defined by the Business Admin, but at the API level you determine which operations are assigned to which scopes. This in turn determines which licenses will be available to app developers requesting access to your API.

For example, let's say your API includes a set of operations relating to calendar functionality and another set of operations relating to email access and management. App A might only need access to the calendar functionality, and App B might include an email client, requiring access to the operations relating to email. The scope mapping feature enables you to group individual operations into logical groups that can be separately packaged into a license for App A and another for App B.

As another example, let's say you want to free offer access to your GET operations, and a higher level of access, for a fee, to all operations including ADD, MODIFY, and DELETE. The Business Admin defines Read and Modify scopes, and then assigns each to a separate license. The API Admin assigns GET operations to the Read scope and assigns all operations to the Modify scope. Users who choose the paid license get access to all operations; users who choose the free license can only access the GET operations.

At runtime, when a request is received to an API proxy from a particular app, the request is only passed through to the API if it is using one of the specific operations covered by the license governing the API contract.

To perform scope mapping

  1. From the API Details page, from the drop-down list at the top right, choose Manage Licensing.
  2. On the Manage Licensing page, check the Enable Licensing for API box to enable the Licenses feature for the API.
  3. Choose a scope mapping approach:
    • API-Wide Mapping: Choose this if you're not subdividing your operations for licensing purposes.
    • Operation-Specific Mapping: Choose this if you'll want to grant access to some portions of your API separately.
  4. In the Scope column, click Select. The Select Scope popup displays. Choose one or more scopes and click Confirm. If you assign scopes to an operation, all apps with licenses that include one of those scopes can use the operation.

    Version 2019.1.31 and later: You can also use the Search bar to find the scopes you need in the Select Scope box.

    Note: Scopes are set up by the Business Admin. If you need scopes that are not on the list, ask the Business Admin.

  5. Operation-Specific Mapping only: Repeat for each operation.

    Note: If you are using operation-specific mapping, assign at least one scope to each operation, even if it's a Free scope that's available to all.

  6. Click Save.

I want to exclude an operation so app developers can't use it. How do I do that?

You might have one or more operations that are part of your API but you don't want to make them available for app developers. Perhaps they are still under development or being tested.

If you want to make sure that no app can access these operations, the best way to do it is with scopes and licenses. You can use a scope that isn't assigned to any license, and use the API scope mapping wizard to assign that scope to the operation. When you're ready to share the operation, you can update the scope assignments, assigning a scope that's assigned to a license so that app developers can choose to access it.

How do I inform app developers about available licenses and API access?

As a standard practice, a list of available Licenses and the level of App Access provided by each License should be included in the documentation for your API.

How do I edit the license on an API access request?

An API Administrator can change the license for a specific API Access Request prior to approving the request.

If you want to review the license scope of API access requests before approving, make sure you've selected the This API requires approval option in the API setup. If the API is set to auto-approve requests, you won't have the opportunity to modify the license.

To edit the license scope for a pending API access request

  1. Go to APIs > My APIs > choose API > Apps.
  2. Select the API Access Request you want to modify. It must have a status of Access Pending.
  3. Click Edit. The API Access Wizard launches and loads the Licenses page.
  4. Change the license option as needed.
  5. Click through the rest of the wizard and then click Save.