When you define an API in the WSO2 API Manager you have three options that will govern API visibility. These options are:

1. Public
2. Visible to My Domain
3. Restricted by Roles

When you define the API you can also determine who can subscribe to an API. The choices here are:

1. Available to the current tenant only
2. Available to all tenants
3. Available to specific tenants

In this WSO2EASY blog we will look at these options and see to what extent they work. For instance, when an API is published as Public but later is changed to Restricted by Roles, does that impact existing subscribers?

There is also the possibility of scopes to be added to the token generation. A user without that scope will not be able to access the API even if they subscribed to it.

Create a tenant

Let’s start by defining a tenant domain because we need that to test the second option. Tenants are defined on the Configure tab in the Management UI of the API Manager. We create the Yenlo.com domain in this example.

We also create a role called “pubrole”. This role is empty, no permissions are granted. The role is used to govern visibility as well as used as a scope in the OAUTH2 tokens. Roles can be added to the API Manager using the Main tab Add Users  / Roles.

Similarly create a “testrole” that we will use for scopes.

You will have two roles without any permissions, just a name.

Defining the visibility

Let’s say that we have three API’s:

1. Pizzashack
2. WeatherAPI
3. Rijksmuseum

The Pizzashack API is visible to my Domain, the others are public.

Public

A Public API is exactly what it says: an API that actually is available to all users of the public store, regardless of the domain. In order to test you need to be subscribed of course which is only available after login.

Restricted to My Domain

In this case the API is visible to the users from the same domain where the api was created in or even imported to. In case of the carbon.super domain (the default setting) you need to log in to the domain to see the API.

Restricted by Roles

When we change the visibility of the API to “restricted by roles” for the Pizzashack and add “pubrole” as the role that is needed, for non-subscribed users without the “pubrole” the API is not visible. For users who are subscribed it does not change. The API is still visible and the user is subscribed to the API and can still use it.

Subscribing

The three subscription options indicate who can subscribe to the APIs. To reiterate:

1. Available to the current tenant only
2. Available to all tenants
3. Available to specific tenants

In conjunction with the visibility you can create a setup where for instance:

• a public API can be subscribed to by all tenants
• a public API can be described by specific tenants
• a domain specific API can be subscribed by the current tenant (so only that domain)

There is some redundancy since an API visible to a domain can only be subscribed to within that domain since otherwise it will not be visible. But with visibility and subscriptions you can actually create special setups.

Invoking an API

Lastly, you might want to have a scope (a role) to be present in the token creation so that even if someone is from that domain, they cannot invoke all of the API’s.

In this case we introduce another role, in this case “testrole” and we create a simple user from the self-signup function. We add “testrole” to that user.

In the Pizzashack definition we add a scope (testscope2) with a role of “testrole”.

When the user wants to invoke the API once subscribed he or she can see a scope is required.

Without the scope

{
  "fault": {
    "code": 900910,
    "message": "The access token does not allow you to access the requested resource",
    "description": "Access failure for API: /pizzashack/1.0.0, version: 1.0.0 status: (900910) - The access token does not allow you to access the requested resource"
  }
}

With the scope we get a response.

Conclusion

Visibility, ability to subscribe and scopes help you define API’s with the right level of authorization. However, getting them to work in your envisioned setup will take same time. Hopefully this blog has helped you to set up your environment.

If you have any questions about this blogpost contact us via the comments section of this blog. View also our WSO2 Tutorials, webinars or white papers for more technical information. Need support? We do deliver WSO2 Product Support, WSO2 Development Support, WSO2 Operational Support and WSO2 Training Programs.