Scopes

Configure and manage scopes as part of setting up licenses for API access.

API Platform Version: 8.1 and later

Table of Contents

  1. What is a scope and how does it work?
  2. What are the visibility rules for a scope?
  3. How do I configure a scope?
  4. How do I add a child to a scope?
  5. How do I move a scope?
  6. What is the relationship between a license and a scope?
  7. How do I edit a scope?
  8. How do I delete a scope?
  9. Related Topics

What is a scope and how does it work?

A scope is an entity that you define to represent any subdivision of an API that you might want to have separate control of. In the platform, the Business Admin can define a set of scopes and can then define licenses that include scopes as building blocks. A license is made up of one or more license terms plus legal agreements; a license term is made up of one or more scopes plus Quality of Service policies.

The API admin can then map the scopes to actual operations, completing the license definition for that specific API.

Visibility:

You can also manage API visibility using scopes. For example, you could define a scope as private. Whatever the visibility setting is for the API, operations that are part of a private scope can only be seen by an individual who is a member of a group specifically invited to have visibility of a license that includes the scope.

Granularity:

You can define one scope for all operations or use multiple scopes. For example, you could have a scope for Read-Only operations and a second scope for all other operations. Or you could define one public scope for all operations except two or three that are in beta, and create a new private scope, Beta, for the new ones. You could then invite select users to access the beta operations, while your main body of users are unaware that beta testing is going on. They would simply not see the beta operations.

Scopes are a tool that enhance the manageability of the API by allowing you to break the API into smaller units so it can be shared or monetized in different ways.

Hierarchy:

Scopes can be configured in a hierarchy, and can include sub-scopes in multiple levels:

  • If a user has visibility to a scope, the same user has visibility to all sub-scopes.
  • If an app has access to a scope, the same app has access to all sub-scopes.

Management:

Some points to note with regard to managing scopes:

  • Business Administrators can add, modify, or delete a scope.
  • You can add a top-level scope using the Add Scope function.
  • You can add a child to any existing scope, at any level. Just highlight the scope and select Add Child.
  • You can edit an existing scope, but you cannot change the scope name.
  • Each scope includes a Delete function that allows you to delete the definition. Scope definitions cannot be removed if they are in use (used in a license that's referenced in an active API contract), or if any active license definitions include the scope.

Configuration:

You define scopes in the Administration > Scopes section and then reference those scopes when defining a License.

Back to top

What are the visibility rules for a scope?

The following visibility rules apply for a scope:

  • A user can view all public scopes for an API that's public. If the API is private, the user must have visibility of the API, but needs no other special invitation.
  • A user has visibility of operations that are assigned to all private scopes (including all its descendant scopes) that are included in all licenses that the user has permission to see based on one or more groups that the user belongs to.
  • An app developer doesn't see scope information. The developer simply chooses a license when requesting API access. The developer's scope access is controlled by a) the scopes that are included in the license definition, and b) the operations that are assigned to the scope.

Back to top

How do I configure a scope?

You can configure a scope in the Administration > Scopes section of the platform. Some points to note:

  • The scope definition includes name, description, and other properties such as visibility.
  • The scope definition is the broad stroke; the API Admin fills in the specific details when assigning scopes to operations at the API level.
  • Scopes are organized on a Scope Definitions page using a vertical navigation approach.
  • The top level tier of the scope hierarchy represents the parent scope.
  • You can move a scope anywhere in the hierarchy by selecting and dragging the scope to a new position.
  • The +Add Scope function on the left panel allows you to add one or more scopes.
  • You can add multiple levels of child scopes to an existing scope by clicking a scope definition in the hierarchy on the left panel, and selecting the +Add Child function on the right panel.
  • You can modify a scope, but you cannot change the scope name.
  • When you delete a scope, any child scopes are also deleted.

Note: Scopes can be configured by Business Administrators only.

To add a scope:
  1. Navigate to Administration > Scopes.
  2. On the Scopes page, click +Add Scope. In the right panel, specify the Scope Name, Description (Short and Full), Visibility (Public/Private), Sandbox Access and Live Access options, and OAuth.

    Item Description
    Name Specify the scope name.
    Short Description Specify a short description for the scope.
    Full Description Specify a full description for the scope.
    Visibility

    Select a visibility option. The following rules apply:

    • Documentation about public scopes is visible to all users, for a public API, or all users who have visibility of the API, for a private API.
    • If a scope is private, a user must be specifically invited in order to have visibility of a license that includes the scope. If not specifically invited to the license, the user does not see the license and cannot view associated documentation.
    Sandbox Access

    Select a Sandbox Access Option:

    • Anonymous Access Allowed: This option auto-approves a Sandbox API request if all Licenses in the API Access Request are configured with Auto Approved.

      Note: If one or more Licenses are configured with Approval Required, the API Access Request will be placed into a "Pending" state.
    • API Access Request Needed: This option places a Sandbox API request into a "Pending" state.
    Live Access

    Select a Live Access Option:

    • Anonymous Access Allowed: This option auto-approves request to access an API in a Live implementation if all Licenses in the API Access Request are configured with Auto Approved. Not recommended.

      Note: If one or more Licenses are configured with Approval Required, the API Access Request will be placed into a "Pending" state.
    • API Access Request Needed: This option places a request to access an API in a Live implementation into a "Pending" state.
    OAuth If you are using OAuth, the following properties are available, and are selected by default:
    • Default Scope: If a scope is set to be a default scope, then each grant request without a specific scope will include the scope as part of the requested scope.
    • User Authorization Required: If a specific scope does not require user authorization, the OAuth Authorization Access point will skip the user’s authorization page and assume that the user authorizes the specific scope as part of the grant to the application.
  3. Click Save.
  4. After you've saved your scope, you can add a child scope using the +Add Child function in the right panel. See How do I add a child to a scope? for more information.

Back to top

How do I add a child to a scope?

After you've saved a scope, you can add a child scope. You can create multiple levels in the scope hierarchy.

To add a child scope:
  1. Navigate to Administration > Scopes.
  2. On the Scopes page, in the left panel, click the scope for which you want to add a child scope.
  3. In the right panel, click Add Child.
  4. Define the scope as described in How do I configure a scope?

Back to top

How do I move a scope?

You can move a scope anywhere in the scope hierarchy by selecting the scope and dragging it to a new position in the list. You can also move a scope to a higher or lower level in the hierarchy.

To move a scope:
  1. Navigate to Administration > Scopes.
  2. On the Scopes page, in the left panel, click the name of a scope that you want to move. Hold down the mouse and drag the scope to the new location in the hierarchy. It can be higher, lower, or at the same level.
  3. Release the mouse, and then click OK at the confirmation message.
  4. Repeat as needed to reorganize your scope hierarchy.

Back to top

What is the relationship between a license and a scope?

A license is a logical grouping of license terms plus optional end-user legal agreements. Each license term can include one or more scopes and one or more Quality of Service (QoS) policies. Licenses are defined by the Business Admin.

At the API level, if the Licenses feature is used, API operations are assigned to scopes. Scopes are the link between the API and the license.

When an app developer requests access to the API as part of the API Access Request process (via Access on the API > Details page), the developer sees a choice of one or more licenses. The scopes are not seen by the developer, but are part of the license definition.

Note: If a License or scope that is referenced by a License is updated, any pending or approved API Access Requests are automatically updated.

For more information, see the API Access section.

Back to top

How do I edit a scope?

You can modify a parent or child scope as long as it isn't in use in an API access contract.

To edit a scope:
  1. Navigate to Administration > Scopes.
  2. On the Scopes page, in the left panel, click the scope you want to edit.
  3. In the right panel, click Edit, and then update the scope as needed.
  4. Click Save.

Back to top

How do I delete a scope?

You can modify a parent or child scope as long as it isn't in use in an API access contract. If you delete scope that has children, the child scopes are also deleted.

To delete a scope:
  1. Navigate to Administration > Scopes.
  2. On the Scopes page, in the left panel, click the scope you want to delete.
  3. In the right panel, click Delete, and then click OK to confirm.

Back to top