Before you start to create your Developer Portal, explore the sample Echo API Developer Portal provided with 3scale. The Echo API Developer Portal is your starting point for creating your own Developer Portal. You do not create a Developer Portal from scratch. Instead, you modify the native Echo API Developer Portal to create a Developer Portal that has the look and feel that you want.

After exploring the Echo API Developer Portal, make some changes to it before you start to create your own Developer Portal. These practice steps are helpful preparation for creating your Developer Portal.

This procedure replaces the sample 3scale Echo API landing page heading with a heading for the common Swagger Petstore API. It also shows you how to update your Developer Portal to display documentation for the Petstore API.

3scale provides many features for customizing the native Developer Portal to create your own Developer Portal.

During development of your Developer Portal, anyone who needs to view your Developer Portal must specify an access code. Keep this access code in place while API providers are performing the required tasks for opening your Developer Portal to access by API consumers The access code ensures that only you or anyone with this code can view your Developer Portal. The access code is in the Domains & Access page, which is available in the Admin Portal by selecting Audience > Developer Portal > Domains & Access.

The following list introduces some of the features for modifying the native Developer Portal:

In the Developer Portal > Content environment, when you scroll down in the resource hierarchy you can see headings for Layouts and Partials. Layouts and partials let you reuse content in your Developer Portal:

Layouts and partials have draft and published states as well as a version history. For example, you can save a draft, publish it, and revert to the last published version.

To learn about editing and writing code for layouts and partials, see the 3scale Liquid Reference.

Typically, you want to use your own images, files, or other assets to customize the native Developer Portal. To do this, add the file to the Developer Portal content library, make a note of its path in this environment, and then in code you add a link to the location of the file in the content library.

Before you start customizing the native Developer Portal to create your own Developer Portal, you should have a plan for its basic elements, reusable content, page hierarchy, page headers and footers, and branding.

Before you can give API consumers access to your Developer Portal, API providers must perform the following tasks. These tasks can be performed concurrently:

The last task you must perform before your Developer Portal goes live is to remove the access code. Do this only after authentication for access to your Developer Portal is in place and after you have thoroughly tested your Developer Portal to confirm that it is behaving as you want it to.

To delete the access code, display the Developer Portal > Content environment. In the lower right, click Open your Portal to the world and confirm this action.

Beyond the requirements for opening your Developer Portal to API consumers, you might want to do the following:

In 3scale 2.8, external assets were moved from Content Delivery Networks (CDN) to the 3scale codebase. Consequently, starting with 3scale 2.8, the native Developer Portal is created by using the cdn_asset Liquid tag. If you are upgrading from a 3scale release that is earlier than 2.8, you must update your Developer Portal to use the new assets with the cdn_asset tag. With the use of this tag, there is no longer a dependency for downloading assets from external websites.

To remove approvals, go to Audience > Accounts > Usage Rules and in the Signup section, make sure the option of Developers are allowed to sign up themselves is checked.

Optionally, if you have account and service plans enabled, scroll down the page and make sure the option Change plan directly is enabled in both cases:

Application plans

Optionally, if you have account and service plans enabled, choose default plans for those too

Account plans (optional)

Service plans (optional)

Once you’ve made your desired settings changes, test out the results by going to your Developer Portal and attempting to sign up as a new developer. Experiment and make any necessary adjustments to get exactly the right workflow for your API. When you’re happy with the workflow, it’s a good time to check your email notifications to make sure they provide the right information for your developers.

You should be familiar with layout and page creation procedures as well as with the basics of Liquid formatting tags. For more details about liquid tags, see Liquid reference. "Multiple Service" functionality must also be enabled on your account (available for Pro plan and up).

It’s strongly recommend that you read about signup workflows, so you’ll have the whole setup prepared and know how it works.

Start the process by creating a new layout, which will serve as the template for your multi-service signup page. Go into the Layouts section of the CMS system, and create the new layout. You can call it multipleservicesignup to be able to easily distinguish it from the other layouts. In the editor, paste the general structure of your standard layout (such as home or main layout). Now delete everything you don’t need – all the containers, sidebars, additional boxes, etc.

Having created the backbone of your layout, proceed to customizing the code for signup.

By default, the username/email and password authentication is enabled on your developer portal. Usually there is no change to be made here, as this is a standard way for your developers to create an account and to login.

However, in some rare cases you might want to remove this authentication type. To do so, edit the Login > New template as in the screenshot below:

If you need to add back the username/email and password authentication to your developer portal, just remove the liquid comment tags added in the previous step.

In order to enable your own GitHub application, first you will need to create one and retrieve the corresponding credentials.

There are two different ways you can configure authentication via GitHub:

To make changes to this default configuration, you can go to your 3scale Admin Portal, in Audience > Developer Portal > SSO Integrations you will see the following screen:

Click on GitHub to access the configuration screen:

From this screen you can:

Red Hat Single Sign-On (RH-SSO) is an integrated Sign-On solution (SSO) that, when used in conjunction with 3scale, allows you to authenticate your developers using any of the available RH-SSO identity brokering and user federation options.

Refer to the supported configurations page for information on which versions of Red Hat Single Sign-On are compatible with 3scale.

First of all, the API consumer must have an account in your Developer Portal. You can import your users to 3scale using the Account Management API or create them manually. Find the Account Management API in the 3scale ActiveDocs, available in your Admin Portal, under the Documentation (question mark icon (?) in the top right corner) → 3scale API Docs section.

Once the user exists, you can use an API request call to generate a URL with a built-in SSO token:

curl -X POST -d "provider_key=YOUR_PROVIDER_KEY&username=USERNAME&expires_in=60" https://YOUR_ADMIN_PORTAL.3scale.net/admin/api/sso_tokens.xml

There are 2 parameters in this call: username to specify who you are requesting the token for and expires_in which is the number of seconds that the token will be valid for (it defaults to 10 minutes).

You can also pass an additional parameter redirect_url with a location to redirect the user after a successful login. This parameter should be percent encoded. The XML response will contain a URL with a secret token included:

<?xml version="1.0" encoding="UTF-8"?>
<sso_url>
https://YOUR_DEVELOPER_PORTAL/session/create?expires_at=1365087501&token=Q0dNWGtjL2h2MnloR11yWmNwazVZY0NhenlabnBoRUNaNUlyWjZaVG8wMnBGdVNhT0VGN1NUb3FRc1pwSnRrclBZSTIwOUFwRkVTc3NuK1JTbjUrMEE9PS0tY1ZrOGFldzFJNkxna1hrQzQyZ0NGQT09--712f2990ac9248ab4b8962be6467fb149b346000
</sso_url>

The response contains an RH SSO login URL with a token:

https://YOUR_DEVELOPER_PORTAL/session/create?expires_at=1365087501&token=Q0dNWGtjL2h2MnloR11yWmNwazVZY0NhenlabnBoRUNaNUlyWjZaVG8wMnBGdVNhT0VGN1NUb3FRc1pwSnRrclBZSTIwOUFwRkVTc3NuK1JTbjUrMEE9PS0tY1ZrOGFldzFJNkxna1hrQzQyZ0NGQT09--712f2990ac9248ab4b8962be6467fb149b346000

The URL contains all the required information for the 3scale Developer Portal SSO to log you in. You can embed it directly into web. However, the URL can expire before the user clicks it, so it is recommended to have a generic link on your page that will dynamically request a fresh SSO URL and redirect to it. This way, the user will be seamlessly logged in to the Developer Portal.

When creating restricted sections, it is useful to do it so that each section maps to a logical group of users. For this example, assume that there is a group of developers called "partners".

Create a new section in the Developer Portal for every page or group of pages that you want to restrict access to. Uncheck the "public" status field. Then drag and drop any pages you want inside this section.

Create a group and give it access to the section you created.

Now every time you have to grant one of your users access to this section, all you have to do is assign them to this group. To do this, go into the corresponding account detail page, then to "Group Permissions." Once there, check the boxes for the sections you want to allow.

Liquid tags are a very powerful way to customize your Developer Portal. Use them here to hide or display parts of a page based on a condition. 3scale allows you to create custom fields for accounts, applications, and users. You can leverage this to store information that is useful for you as the API provider. Here you’ll create an custom field attached to all accounts and use it to indicate whether a given account is a partner or not. You can create this field by going to Audience > Account > Field Definitions. Add a field to the Account section, and mark it as hidden so it will not be displayed on the signup page or anywhere else on the portal.

With the custom field in place, you are now able to show special content to partners by wrapping it in a conditional like in the following snippet:

{{ if current_account.extra_fields.partner == 'true' }}
  // content only accessible to partners
{{ endif }}

Or use the inverse logic if it suits your case better:

{{ unless current_account.extra_fields.partner == 'true' }}
  // content forbidden for partners
{{ endunless }}

From here on, whenever you want to show these pieces of hidden content to a user, all you need to do is type in 'true' in the partner field of their account detail page.

You can provide access to restricted content to developers based on a change in state. For instance, when they upgrade their application plan.

Streamline the process of access provision by using webhooks together with the Account Management API. The Account Management API is in the 3scale ActiveDocs, available in your Admin Portal:

In addition to the two ways to restrict access to content described above, there is another technique that can be useful: requiring a logged-in user.

This is very easy to achieve using Liquid tags. All you have to do is wrap the content that will be available only for logged-in users inside the following conditional:

{{ if current_user }}
  // only visible if the user is logged in
{{ endif }}

This section explains how to enable liquid markup processing in layouts and pages.

9.1.1. Enabling Liquids

Liquid markup processing is enabled by default for all partials and email templates. Enabling them on layouts is done by ticking the checkbox right under the system_name input field. However, to enable them on pages, you will have to go to the advanced options section of the page.

Just expand the Advanced options section and mark the Liquid enabled checkbox. From now on, all the liquid markup will be processed by the internal engine, and the Developer Portal built-in editor will also add code highlighting for liquid.

<!-- if we are inside '/documentation' URL -->
<li class="{% if request.request_uri contains "/documentation" %}active{% endif %}"><!-- add the active class to the menu item -->
  <a href="/documentation">Documentation</a>
</li>

This section explains how you can use liquid tags to customize email templates.

This troubleshooting section will help you debug and fix typical errors that might occur.

These email templates fall under the account management category:

For these templates, you can use the following liquid drops:

Additionally, the following template:

The email to invite additional users to an account:

You can use the following liquid drops:

have access to:

The following email templates all deal with application and application plan notifications.

They have access to:

Application plan change request notification email templates:

They have access to:

The following email templates contain a number of available drops, such as:

They have access to:

As well as all of the above liquid drops, the following application plan messages…​

have the additional liquid drops listed

More liquid drops accumulate for the following email templates for application keys:

The following email template…​

has access to:

Additionally, the following templates…​

share the following liquids:

The following email templates:

have access to:

As well as the above liquid drops, the following service templates…​

have the additional liquid drops listed:

The following email templates…​

have access to:

There is a default stylesheet, default.css. It is quite large and complex, so rather than extend it, it’s better to create your own stylesheet for any of your own customizations to overwrite the defaults. You create a new stylesheet the same way you create a page (just remember to choose an appropriate MIME content type in the advanced page settings).

It’s important that the selected layout is blank. Otherwise the page layout HTML will obscure the CSS rules.

Add the link to your custom CSS in each of your layout templates (or in a partial if you have a common HEAD section) after the link to bootstrap.css. For example:

<link rel="stylesheet" href="/stylesheets/custom.css">

Now enjoy the beauty of your own unique branding!

The general idea is to define a separate layout for each of the different page styles in your portal. There is one standard layout called Main layout when you start. Do not make any changes to this layout until you are an expert at using the Developer Portal because this layout is used by all system-generated pages.

Typically, you want a unique style for the home page of your portal. The Main layout template is a starting point for your customizations. To create a page layout template:

The first and most important thing to do is identify what you want to hide. To do that, use Firebug (or any other developer tools such as Chrome Developer tools or Opera Dragonfly). Choose the desired element, and in the console, right click on it and select Copy CSS path. This way you save the exact CSS path to make it easy to manipulate. Remember, if the element is a part of the sidebar navigation widget, you’ll also have to specify which position in the list. For this, you can use either the "+" selector (for example, to choose 3rd li element: ul + li + li + li) or the :nth-child(n) CSS3 pseudoclass.

Now, having identified the elements, you can change their display settings. Depending on the type of element, you can choose from two possible methods: CSS manipulation or jQuery script. CSS manipulation is more lightweight and reliable, but doesn’t work well for some kinds of elements that exist on a number of pages (for example, the 3rd element in the sidebar of the Admin Portal’s Dashboard also exists in the Account section but has a different value). Some trickier implementations require use of CSS3 which is not supported by old browsers. In the next two steps, you’ll see both of these approaches.

As an example, try to hide the latest element from the Dashboard page. Following the first step, you have identified its CSS path as:

#three-scale .dashboard_bubble

Keep in mind that it’s the second box with the same path, so you’ll use the "+" selector. Your path will now look like this:

.main_layout #three-scale .dashboard_bubble + .dashboard_bubble
/* or */
.main_layout #three-scale .dashboard_bubble:nth-child(1)

Changing display property to none makes that box invisible:

.main_layout #three-scale .dashboard_bubble:nth-child(1) {
  display: none;
}

If you have a trickier element to hide such as a sidebar menu element, it’s better to use some jQuery. The CSS path of these elements is identical on the Dashboard and Account sections, and you don’t want to hide elements in both sections. So choose the element based on the CSS path and the content. In this example, assume you want to hide the messages section from the Dashboard’s sidebar. Your CSS path is:

#three-scale #submenu li a

In order to match the content, you’ll use the .text() function. You’ll also include the code inside the document’s head and inside the ready function so it’s executed after all the content has been generated.

The resulting code snippet will look like this:

$(function() {
  $('#three-scale #submenu li a').each(function() {
    if ($(this).text() == "Messages")
      $(this).parent().css('display', 'none');
  });
});

This is not the only solution. It just shows one possible way of doing it. The same example could be done using pure CSS with CSS3 selectors basing on the attributes values. For the complete CSS3 selectors specification, take a look here.

This part of the workflow is easy to set up in the Admin Portal by following the steps below.

Go to Audience > Developer Portal > Signup, where you will be presented with a blank page to populate with your signup legal terms. You can use any combination of HTML, JavaScript, and CSS. There is also some toggling code provided by clicking Insert toggling code. The content you write in this box will appear just above the Sign Up button on the Signup page of your Developer Portal.

Once you have filled out your Terms and Conditions, save them by clicking Update.

If you have used the toggling code, it will display "By signing up you agree to the following Legal Terms and Conditions" followed by a link that toggles between showing and hiding the Terms and Conditions you specified.

This is placed on the Signup page by default, but it is a partial (signup_licence) that can be included anywhere on your Developer Portal. To remove this from the Signup page, simply remove the {% include 'signup_licence' %} line from the page. Similarly, if you want to include it somewhere else, you can use the same partial by means of the snippet, which can be placed anywhere on your Developer Portal.

You might also want your users to accept another set of Terms and Conditions when they create a new application (new_application_licence partial) and/or when they subscribe to a new service (service_subscription_licence partial). To set these up, you can follow the same procedure outlined above.

You can also define other URLs where different policies reside. Set them up by going to Audience > Billing > Credit Card Policies and setting the path where your policy pages will be located.

In order for these links to work, you will then need to create new pages in the Developer Portal.

Once that is done, you can reference them using the URL’s liquid drop. For example:

<a href="{{ urls.credit_card_terms }}">Legal Terms</a>
<a href="{{ urls.credit_card_privacy }}">Privacy</a>
<a href="{{ urls.credit_card_refunds }}">Refunds</a>

And that’s it!