API Settings and Visibility

Manage API settings relating to API access as well as visibility.

Table of Contents

API Settings

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

API Visibility

• What is a private API?
• How do I manage API visibility?
• What are the API visibility settings?
• How does the API visibility option work?
• What API License visibility options are supported for groups?
• How do I edit the API visibility scope for a Group (API Administrator)?
• How do I create an API Scope Group?
• What happens after I accept an invitation to an API Scope Group?
• 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.

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.

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.

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.

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.

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. For information on the values, see What are the API visibility settings? below.
5. Click Save.

What are the API visibility settings?

There are three valid values for API visibility:

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

How does the API visibility option work?

From the top menu, choose APIs > My APIs > choose API > Visibility. This 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.

Note: These fields display on the Visibility page only if the Licenses feature is enabled for the API.

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. The 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 the API includes some Scopes that are defined as Private. Only invited users can see the documentation related to the private sections of the API. The 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. The 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.

What API License visibility options are supported for groups?

From the top menu, choose APIs > My APIs > choose API > Visibility.

The Visibility page displays a list of groups that have been invited to have visibility of the current API.

If there is more than one license available for the API, you can manage the specific license or licenses that are available to a group that has been invited to have visibility of the API. After inviting the group, click Edit Licenses.

The following license scope levels are supported.

Scope Level	Description
Complete API Visibility	All of the API documentation/downloads will be visible to the API group. All licenses will be available for selecting when a member of the API group clicks the Access button to request API access for an app.
Partial API Visibility	When there is more than one available license that could be assigned to the group, this option allows the user to choose one or more specific licenses that will be available when a member of the API group clicks the Access button to request API access for an app.

To configure license visibility for an API group

1. From the top menu, choose APIs > My APIs > choose API > Visibility > Groups. The Groups Summary page displays.
2. Select the group and click Edit Licenses. The Edit Visibility License page appears.
3. Choose one of the options:
   • Complete API Visibility—Gives members of the group complete visibility to the API.
   • Partial API Visibility—If the API supports multiple licenses, choose one or more to make them available to group members. An example is shown below.

     

4. Click Save.

How do I edit the API visibility for a group?

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

To edit the license scope for a group

1. From the top menu, choose APIs > My APIs > choose API > Visibility > Groups. The Groups Summary page displays.
2. Select a group from the listing and click Edit Licenses. The Edit Visibility License page is displayed.
3. Click the radio button of the License access option that you want to assign to the current Group. For available options, see What API License visibility options are supported for groups? above. Specific available licenses are determined by the API's scope assignments, set up on the Manage Licensing page (see What is scope mapping and how do I set it up?).
4. Click Save to commit your changes.

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.

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 on your API list.
• The Access function is available on the APIs > My APIs > choose 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.

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 or the groups they have membership of.

In this scenario . 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.

Generated API documentation displays operations to users according to the scopes assigned to the operations (see What is scope mapping and how do I set it up?) and the view privileges of the user. You can also add special tags to authored 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.

Note: Scopes applied to API operations filter API documentation in the API > Documentation view. They also filter operations in API > Test Client, but only when there is a contract between an app and an API. Until the contract is applied, the operations are not filtered in Test Client. If this is a concern, you can set your API so that anonymous access is not allowed (see Should I allow anonymous access?).

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?

Related Topics