How to Manage API Visibility with Licenses

A how-to guide for creating a simple setup to use licenses to control the visibility of APIs.

Table of Contents

Overview

This article describes how to create a really simple environment that uses licenses to control visibility and access to the operations of an API. This is typically used in conjunction with content visibility controls and documentation file visibility controls to provide a comprehensive solution.

This article provides a simple set of instructions to get you started. For a comprehensive guide to the documentation visibility controls, refer to API Documentation Tagging.

The licenses feature is extremely powerful, and as such can be a little hard to understand. In this example, we are going to create a public API, and then use license restrictions to make some operations within the API private, granting access to these operations to members of an admin group.

Notes:

  • Making an operation private will hide it within product features such as the Test Client and automatically-generated Swagger documentation.
  • Once you choose to use license for an API, all user-generated documentation will be hidden by default unless you choose to expose it using content and file visibility controls (see links above).

Step 1 - Set up Scopes and Licenses

To keep things really simple we are going to define two scopes, User and Admin, and then we will use these scopes in two licenses, User and Admin.

Note: the Admin license will include both scopes to provide comprehensive access.

  • Log in as a Site Admin or Business Admin.
  • Go to More > Admin >Scopes (/#/system/scopes) to add two new scopes, one named User and one named Admin.
    • User scope—take all the defaults, except for marking it public
    • Admin scope—use all the defaults, ensure the scope is marked private
  • Go to More > Admin >Licenses (/#/system/licenses) to add two new licenses, one named User and one named Admin.
    • User license—check both environments, visibility - public, add a term that includes ONLY the User scope.
    • Admin license—check both environments, visibility - private, add a term that includes BOTH the User and Admin scopes.

Step 2 - Configure API to use Licenses and Map Scopes

Either as you create your API, or after the fact by editing it, set the API to public, and check the use licenses box. This will mean that the public aspects of the API will be visible to anonymous users, private aspects will be hidden.

To determine which operations are public and which are private you will map scopes using the Scope Mapping tool from the API details page.

  • Select operation-specific mapping.
  • Choose the User scope for the operations you want to be public.
  • Choose the Admin scope for operations you want to be private.

Step 3 - Define a Group for Admin users

At this point your API will be visible to all users and the operations to which you assigned the User scope will be visible, but any other operations will be hidden.

  • Go to the main page for your API.
  • Fro the API left menu, choose Visibility, and then choose Groups.
  • Click Create Group to add a new group.
    • Pick a sensible name such as Administrators and provide a description.
    • Select independently-managed.
    • Select private.

Note: if there is no Create Group button, this feature may be disabled in the Community Manager developer portal settings. Check that Admin > Settings > API > Private API Settings > API Scope Groups is enabled. This shouldn't be in play here, because you really should be working with a Public API. In fact, if you're not using a public API, this scenario won't work the way you want it to.

Step 4 - Assign the Admin license to the group

To expose these operations to selected users, you will define a group, assign the Admin license to the group, and then add the selected users as group members.

  • Use the Edit Licenses button for your group
    • Choose Partial API Visibility
    • Select the Admin license

Step 5 - Invite users to the group

Now you can click on the group name and invite users to be members of your admin group. Remember that an invited user will need to accept the invitation in order to become a group member. As soon as they are members they will be able to see the full list of operations in the Test Client and Swagger documentation.

Next Steps - documentation visibility

Now that you have set up the basic license features for API visibility, you can move on to controlling content visibility and documentation file visibility.