The Developer Portal consists of a few elements:

This is the most important part of your view of the Developer Portal system. The content section shows the site structure and hierarchy and provides editing functionality within the same page. This means you can manage the site structure, the pages, and other assets stored in it. The portal’s hierarchy is displayed in the form of a directory tree.

The image above shows a sample view of one of the pages inside the contents section. As you can see, it displays all the files (pages, images, stylesheets, JavaScript, etc.) preserving the site’s path hierarchy. As before, sections are functionally equal to directories.

On the right-hand side, you can see the edit page view. Here you can see the page name (which also indicates whether it’s a standard or built-in page) and a button to add a new element to the content (page, layout, partial, section, or file). Below, you can choose which layout the page will use and toggle the liquid tags functionality. The following part is the text editor, which supports code highlighting, tabulations, line numeration, and much more. The tab buttons Draft and Published switch between the draft and published versions of the edited document. The following two icons list the document’s versions and open a pop-up edit window, respectively.

To edit page content, simply choose the desired layout, set a few additional options such as content type and URL path, and then input the code in HTML, Markdown, or Textile.

Another important feature in this view is the Preview button. You can choose whether you want to preview the published or draft version of the page. Clicking the button redirects you to Developer Portal mode, where you can see the live (or draft) rendered version of the page with a dark grey vertical bar on the right-hand side. This bar contains links to the page, layout, and partials edit views of the Developer Portal. It allows you to swtich between draft and published views.

There’s also a filter feature, which serves not only as a search field but allows you to limit the elements shown to only stylesheets, JavaScript, or any other types specified.

The layouts and partials sections manage the templates and the reusable parts of the page. Their functionality is similar to that of the content section.

The layouts section consists of definitions of the templates used by pages. Layout is the main structure of the page, and the contents of this template will be rendered on every page that uses it. The partials and the actual content of the pages reside inside the templates.

Partials are the reusable parts of code, which can be applied to many places on different pages. For example, the footer is the same on every layout, and the sidebar is the same on a few pages with different layouts.

To include a partial in a layout, partial, or email template use the following command:

{% include "partial_name" %}

As with the other parts of the portal, layouts and partials also have draft and published states and offer a full version history, with the following features:

For a complete guide of liquid tags, check the Liquid Reference guide.

The last elements of the Developer Portal are the redirects and changes sections. They are much less complicated than the content section but are still important and provide some custom functionality.

Redirects help you set up redirects from one portal URL to another. This is useful, for example, when you deprecate an old page and don’t want to change all the links. Redirects cannot be used for built-in Developer Portal pages – they are only for pages created by you.

Last but not least is the changes section. It contains a list of all the newly edited and unpublished pages and gives you the choice to publish them individually or all at once.

This section provides details on updating local assets for the Developer Portal, based on these points:

Hence, to update an existing Developer Portal instance and use the new local assets, follow these instructions:

If you have created other instance files based on the previous ones, such as Main Layout and stats/chart, you will need to update them too. For more information, see the documentation for Liquid tags in porta.

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.

5.4.3. Configuring 3scale

Authentication via Red Hat Single Sign-On won’t be enabled by default. If you want to use your Red Hat Single Sign-On account in conjunction with 3scale to manage access to your developer portal, you can follow the steps below to configure it.

Go to your 3scale Admin Portal, in Audience > Developer Portal > SSO Integrations click on Red Hat Single Sign-On. (Remember: this is an enterprise only feature so you may have to ask your account manager to enable this for you).

On this configuration screen, you’ll need to add the details of your Red Hat Single Sign-On client that you have configured in the previous step:

• Client: Name of your client in Red Hat Single Sign-On
• Client Secret: Client secret in Red Hat Single Sign-On
• Realm: Realm name and URL address to your Red Hat Single Sign-On

Once you’ve entered those, check the "Published" box and click Create RH-SSO to make it available on your developer portal.

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

A webhook is a custom HTTP callback triggered by an event selected from the available ones in the Webhooks configuration window. When one of these events occurs, the 3scale system makes an HTTP or HTTPS request to the URL address specified in the webhooks section. On your end, you can configure the listener to invoke some desired behavior such as event tracking.

To configure webhooks:

Once you have configured the settings, click Update webhooks settings to save your changes.

The format of the webhook is always the same. It makes a post to the endpoint with an XML document of the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<event>
  <type>application</type>
  <action>updated</action>
  <object>
    THE APPLICATION OBJECT AS WOULD BE RETURNED BY A GET ON THE ACCOUNT MANAGEMENT
    API
  </object>
</event>

Each element provides information:

If you need to provide assurance that the webhook was issued by 3scale, expose an HTTPS webhook URL and add a custom parameter to your webhook declaration in 3scale. For example: https://your-webhook-endpoint?someSecretParameterName=someSecretParameterValue. Decide on the parameter name and value. Then, inside your webhook endpoint, check for the presence of this parameter value.

If you experience an outage for your listening endpoint, you can recover failed deliveries. 3scale will consider a webhook delivered if your endpoint responds with a 200 code. Otherwise, it will retry 5 times with a 60 seconds gap. After any recovery from an outage, or periodically, you should run a check and if applicable clean up the queue. You can find more information about the following methods in ActiveDocs:

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!

By the end of this tutorial, you will have a Developer Portal up and running to promote your API, allow developers sign up for accounts, and access their API keys.

There are additional areas interacting with your Developer Portal that you can configure: