API Visibility, Licenses, and Settings

Manage API visibility, configure license scope to determine what licenses will be offered for the API, and manage settings relating to API access.

API Platform Version: 8.1 and later

Table of Contents

API Settings

  1. What is the difference between Sandbox and Live implementations?
  2. What is auto-connect?
  3. How do I set up auto-connect for my API?
  4. How do I set up my API to allow anonymous access?

Scopes and Licenses

  1. How do I determine what licenses will be available for my API?
  2. How do I edit the license on an API access request?
  3. What is scope mapping and how do I set it up?
  4. How do I inform app developers about available licenses and API access?
  5. I want to exclude an operation so app developers can't use it. How do I do that?

API Visibility

  1. What is a private API?
  2. How do I manage API visibility?
  3. How does the API visibility option work?
  4. What API License visibility options are supported for Groups?
  5. How do I edit the API visibility scope for a Group (API Administrator)?
  6. How do I create an API Scope Group?
  7. What happens after I accept an invitation to an API Scope Group?
  8. What about API documentation visibility?

API Settings

What is the difference between Sandbox and Live implementations?

Each implementation is configured by the API Admin; each has unique endpoints. A common scenario is outlined below:

  • The Sandbox endpoint is a unique gateway URL that provides access to the API's Sandbox implementation—generally used for testing. App developers must request access; in some cases, Sandbox access might be auto-approved.
  • The Live implementation is generally used for production traffic, for real transactions rather than testing. Often, the Live implementation has additional policies and security applied. However, the features of each endpoint are completely configurable.

Back to top

What is auto-connect?

The platform's auto-connect feature allows an API Admin to set up the API so that when a new app is created on the platform, a contract with the API is created automatically. The API Admin specifies the details of the access granted with the auto-connect feature, such as whether access is to the Sandbox or Live implementation, or whether access is limited to specific operations or a specific transaction volume (via the Licenses feature, implemented with scope mapping).

You can change the auto-connect details for your API at a later time; however, be aware that if contracts have already been created, those will continue unless you specifically end them.

If your API uses licenses, it's important to set up scope mapping for your API before setting up the auto-connect feature, since the auto-connect settings reference the scope mapping settings.

For instructions on setting up auto-connect for your API, see How do I set up Auto-Connect for my API? below.

Back to top

How do I set up auto-connect for my API?

If you want to grant new apps automatic access to your API, you'll want to set up the auto-connect feature.

Note: If your API is using licenses, set up scope mapping first. Then, follow the instructions below.

To set up auto-connect for an API:
  1. Go to the Details page for the API.
  2. From the drop-down list at the top right, choose Auto-Connect.
  3. In the Set Up Auto-Connect Settings page, check one or more boxes to indicate environment for auto-connect contracts: Live, Sandbox, or both.
  4. Conditional: if your API uses the Licenses feature, a list of scopes is displayed for any environment you selected. Check one or more scopes that you want to allow for an auto-connect contract, for each environment selected.
  5. Click Finish.

Back to top

How do I set up my API to allow anonymous access?

The platform supports app developers testing an API without choosing a specific app (anonymous context).

In order for developers to be able to test your API in this way, you must have some settings in place:

  • API setup, Proxy tab: Allow Anonymous Access is set to Yes.
  • API setup, Proxy tab: This API Requires Approval is set to No.
  • API setup, Proxy tab: there are no security policies added to the API.
  • API setup, API tab: if the API uses licenses, make sure the licenses do not use any private scopes.

Back to top

Scopes and Licenses

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

There are a couple of steps you'll need to complete in your API setup to define the licenses that app developers will see when requesting access to your API:

  1. In your API setup, make sure that the Use Licenses box is checked. On the API Details page, from the drop-down list at the top right, choose Manage Licensing.
  2. Map scopes as needed. For instructions, see To perform scope mapping.

The scopes are the link between your API and the licenses that are offered to app developers. If you have any questions regarding 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.

Back to top

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 > 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.

Back to top

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 and might require 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 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 scopes; 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. First, make sure the Licenses feature is enabled in the API. On the API Details page, from the drop-down list at the top right, choose Manage Licensing. On the Manage Licensing page, make sure the Enable Licensing for API check box is checked. If it isn't, check the box.
  2. 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.
  3. Operation-specific mapping only: For each operation, in the Scope column, click Select. The Select Scope popup displays. Choose one or more scopes for the operation and click Confirm. If you assign scopes to an operation, all apps with licenses that include one of those scopes can use the operation. If no scopes are defined for an operation, it means that no scopes are needed for that operation (the least secure scenario).
  4. Repeat for each operation.
  5. Click Save.

Back to top

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.

Back to top

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 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.

Back to top

API Visibility

What is a private API?

A private API is one that has a visibility setting such that it is visible only to platform users who are members of one or more groups that have been specifically invited to have visibility of the API.

In the platform, any API or other resource that is private is shown with a "lock" icon to indicate privacy.

Back to top

How do I manage API visibility?

When you create an API using the Create a New API function you can control visibility of the API. You can change API visibility as needed.

To change API visibility
  1. Go to the Details page for the API.
  2. Click the Edit button.
  3. On the right, click to view the Advanced Options section.
  4. Change the visibility setting as needed. Valid values:
    • Public: All users can see the API, whether logged in or not. The API is searchable, and displays in the All APIs search filter.
    • Private: Only invited users and groups can see the API. It is visible to the creator, to all API Admins, and to individuals that are members of a group that is invited to have visibility of the API. The API name displays on the API Overview page with a lock icon indicating that it is private.
    • Registered Users: All users who are logged in can see the API. To registered users, the API is searchable, and displays in the All APIs search filter.
  5. Click Save.

Back to top

How does the API visibility option work?

The My APIs > choose API > Visibility menu option allows API Administrators to control who can see the API and its associated resources such as documentation and downloadable files. The API Admin can invite groups to have visibility of the API resources. The following group visibility scenarios are supported:

Scenario Description
Visibility: Public
No Private Scopes.
API is Public; everyone can see it
  • The API does not include any Scopes that are defined as Private.
  • The Visibility section is available for the API.
  • If "Support Scope Permissions" is not enabled for this API, the "Scope Permissions feature is not enabled for this API" message displays on the Visibility home page.
  • If "Support Scope Permissions" is enabled the "This API is completely public and does not have any private sections. There is no need to invite users or groups to see the API." message displays and a listing of Licenses and Scopes (if applicable) displays on the Visibility home page.
Visibility: Public
Some Private Scopes
API is Public but some Scopes of the API are defined as Private.
  • Only invited users can see the documentation related to the private sections of the API.
  • My APIs > choose API > Visibility page includes a table that displays the Private Scopes with the operations that belong to the Scopes and the Licenses that the Scopes are a part of.
  • When inviting Groups to the Private sections of the API, select the Licenses based on the operations that should be visible to the users.
Visibility: Registered Users
No Private Scopes.
All users who are logged in can see the API.
  • The API does not include any Scopes that are defined as Private.
  • The Visibility section is available for the API.
  • If "Support Scope Permissions" is not enabled for this API, the "Scope Permissions feature is not enabled for this API" message displays on the Visibility home page.
  • If "Support Scope Permissions" is enabled the "This API is completely public and does not have any private sections. There is no need to invite users or groups to see the API." message displays and a listing of Licenses and Scopes (if applicable) displays on the Visibility home page.
Visibility: Registered Users
Some Private Scopes
All users who are logged in can see the API, but some Scopes of the API are defined as Private.
  • Only invited users can see the documentation related to the private sections of the API.
  • My APIs > choose API > Visibility page includes a table that displays the Private Scopes with the operations that belong to the Scopes and the Licenses that the Scopes are a part of.
  • When inviting Groups to the Private sections of the API, select the Licenses based on the operations that should be visible to the users.
Visibility: Private
No private Scopes
API is Private.
  • Groups must be invited to see the API.
Visibility: Private
Some Private Scopes
API is Private.
  • Groups need to be invited to be able to see the API. Parts of the API require specific invitations for users to see these sections.
  • My APIs > choose API > Visibility page includes a table that displays the Private Scopes with the operations that belong to the resources and the Licenses that the Scopes are a part of.

Back to top

What API License visibility options are supported for Groups?

The My APIs > choose API > Visibility page displays a list of API Groups that are members of the current API.

  • If you want to manage the visibility of Licenses that an API Group can see for an API Version, you can configure the visibility using the Edit Scope function.
  • Note that when an API Group is invited to an API Version, only Public Scopes will be included in the scope.

Note: the API Administrator can update the license scope configuration for Group Visibility at any time prior to the API Access Request being approved by the API Administrator. Once the API Access Request is approved the Edit Scope function is disabled.

The following license scope levels are supported.

Scope Level Description
Unrestricted Access This option implies all of the API documentation/Downloads will be visible to an API Group. All licenses will be available to select as an API Access Request scope when requesting API access for an app.
Restricted Access This option gives the API Group a set of licenses as part of the visibility scope. A selection of Licenses are presented that can be made visible to a Group by clicking the check box.
To configure license visibility for an API Group:
  1. Navigate to My APIs > choose API > Visibility > Groups. The Groups Summary page displays.
  2. Select the Group you want to edit the scope for and click Edit Scope. The Edit Scope pop-up menu displays.
  3. Based on your visibility requirements, click the Unrestricted Access or Restricted Access radio button. Click OK to commit your changes.

Back to top

How do I edit the API visibility scope for a Group (API Administrator)?

An API Administrator can change the API license visibility for a specific Group.

To edit the license scope for Groups:
  1. Go to APIs > choose API > Visibility > Groups. The Groups Summary page displays.
  2. Select a group from the listing and click Edit Scope. The Edit Scope page displays.
  3. Click the radio button of the License access option you want to assign to the current Group. The following options are available:
    License Option Description
    Unrestricted Access This option implies all of the API documentation/Downloads will be visible to an API Group. All licenses will be available to select as an API Access Request scope when requesting API access for an app.
    Restricted Access

    This option gives the API Group a set of licenses as part of the visibility scope. Click the check box to select the Licenses you want to make visible to the current Group.

  4. Click Save to commit your changes.

Back to top

How do I create an API Scope Group?

If you've added a Private API (visibility = Private), the platform provides an API Scope Group collaboration function via the API > Visibility > Groups page. For more information, see API Scope Groups.

Back to top

What happens after I accept an invitation to an API Scope Group?

If you receive an invitation to an API Scope Group, and accept the invitation:

  • You become an API Scope Group member.
  • The API is visible in the My APIs section.
  • The Access function is available on the API > Overview page of the API.
  • If you are a Leader of the API Scope Group, the Groups page in the APIs section displays your group membership (with Leader role), and a list of members you have personally invited to the API Scope Group.

For more information, see API Scope Groups.

Back to top

What about API documentation visibility?

If your API has restricted visibility, users who don't have visibility of the API will not see your API documentation.

If your API uses licenses, users who have visibility of the API as a whole might not have access to certain operations, depending on the licenses they've selected. In this scenario, you'll need to apply special tags to your API documentation to make sure that users will see the documentation they have access to. By default, untagged API doc content is hidden.

For information on tagging your API documentation, including the different types of tags available, implementation suggestions, and examples, see API Documentation Tagging.

Tip: If you don't care about hiding portions of your API documentation, see My API uses licenses, but I just want my documentation to be visible to everyone. What's the easiest way to set that up?

Back to top