Scopes

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

Table of Contents

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. The chain works like this:

  1. In the platform, the Business Admin can define a set of scopes.
  2. The Business Admin 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.
  3. The API admin can then map the scopes to operations in the API, completing the license definition for that specific API.

A scope is the bridge between the top level of the hierarchy, a license, and the bottom level, an operation. At the business level, the Business Admin defines the scope with a name and basic attributes. Then, at the API level, the API Admin assigns specific operations to one or more scopes for the API. These operations are included in any license that the scope is assigned to.

The app developer never sees scopes; the developer is offered one or more licenses offerings that have been defined for the API. However, scopes are a building block of licenses.

Operations are assigned to scopes; scopes and QoS policies are assigned to license terms; license terms and legal agreements are assigned to licenses.

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 More > Admin >Scopes section and then reference those scopes when defining a License.

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.

How do I add a scope?

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

  • The scope definition includes name, description, and other properties such as visibility. The only required fields are Name and Short Description.
  • Specify the visibility. A public license is visible to app developers when requesting API access for an app.
  • Choose whether anonymous access will be allowed to your Sandbox or Live implementations (not recommended).
  • If you are using Akana as the OAuth Provider you can specify additional OAuth settings.
  • The top level tier of the scope hierarchy represents the parent scope. You can move a scope anywhere in the hierarchy by clicking and dragging the scope to a new position.
  • The API admin assigns scopes to operations at the API level.

You can also:

  • Edit a scope. Highlight the scope and then, in the right pane, click Edit. You can modify a scope, but you cannot change the scope name.
  • Add a child scope. Highlight the scope and then, in the right pane, click Add Child. You can define multiple levels of scope hierarchy.
  • Delete a scope. Highlight the scope and then, in the right pane, click Delete. When you delete a scope, any child scopes are also deleted.

Note: Scopes can only be configured by Business Administrators.

To add a scope

  1. Go to More > Admin >Scopes.
  2. On the Scopes page, click Add Scope. In the right panel, specify the following:
    • Name (required)
    • Short Description (required)
    • Full Description
    • Visibility: If a scope has public visibility, anything mapped to the scope (operations or documents) is visible to all users including anonymous users. If a scope has private visibility, any part of the API mapped to the scope is visible only if the user is a member of one or more groups that either have been invited with a visibility scope containing the private scope or else have been invited with unrestricted visibility.
    • Sandbox Anonymous Access Allowed / Live Anonymous Access Allowed: If anonymous access is allowed for a scope, operations that are mapped to the scope can be used by apps that do not identify themselves to the gateway with any credentials. The app does not even need to be registered in the platform. We recommend not allowing anonymous access to your API, particularly in the Live implementation. For more information, see Should I allow anonymous access?
  3. If you'll be using Akana as your OAuth Provider domain, set the two Akana OAuth Provider Options fields appropriately:
    • Default Scope: If scopes will be used only for the Licenses feature, not for OAuth, clear this setting. For Akana OAuth provider only: If a grant access request does not specify scopes, all scopes that have the Default scope option checked are included in the scope of the grant.
    • User Authorization Required: If scopes will be used only for the Licenses feature, not for OAuth, clear this setting. For Akana OAuth provider only: If a scope is being used for OAuth, user authorization is required for scope access. If an OAuth grant includes all scopes with this option disabled, the resource owner is not required to authorize the grant request.
  4. Click Save. The scope is now available for selection when creating a license. You can also add a child scope.

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. Go to More > Admin >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 add a scope?

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. Go to More > Admin >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.

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.

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. Log in to the Community Manager developer portal as the Business Admin.
  2. Go to More > Admin >Scopes.
  3. On the Scopes page, in the left panel, click the scope you want to edit.
  4. In the right panel, click Edit, and then update the scope as needed. For explanations of the fields and their values, refer to To add a scope. There are also explanations of key fields on the page itself (available on hover).
  5. Click Save. The modified scope is now available for selection when creating a license.

How do I delete a scope?

Before you delete a scope, make sure it isn't in use in any licenses or referenced by any APIs. If a scope is in use, you will see this message:

Scope cannot be deleted. APIs or Licenses are referencing this scope or its children.

If you delete a scope that has children, the child scopes are also deleted.

To delete a scope

  1. Go to More > Admin >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.