Developer Portal Configuration

The look and feel for the entire developer portal can be customized to match your own branding. A standard CSS stylesheet is available to provide an easy starting point for your customizations.

In this HowTo you will add your own CSS customizations, and reload it to put your new styling changes live.

There is a default stylesheet, default.css. This is quite a large and complex stylesheet. Rather than extend this, it is 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 is important that the selected Layout is blank. Otherwise the page layout HTML will obscure the CSS rules.

Then in each of your layout templates (or in a partial in case you have a common HEAD section), after the link to bootstrap.css, you add the link to your custom css e.g.

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

Now enjoy the beauty of your own unique branding!

The look and feel for the entire developer portal can be customized to match your own branding. You have complete control over every element of the portal in order to make it as easy as possible for developers to learn how to use your API. A successful API portal will turn concepts into working apps in no time at all!

By the end of this section you should be familiar with the use of our CMS. We will guide you through it’s structure, usability and functionality.

Let’s start our guide with a general overview of the CMS. As you have probably seen (if you have already taken a look at system), it consists of a few elements:

  • Horizontal menu in the Portal Admin console with access to
    • Content, Redirects and Changes.
  • The main area containing details of the sections above.
  • The CMS mode which is accessible through the preview option.

We will describe each of the sections in more detail.

This is the most important part of the Admin's view of the CMS system. Let’s describe it in more detail.

The Content section shows all the site structure and hierarchy and gives also the editing functionality within the same page. This means that it gives the possibility to manage the site structure and the pages and other assets stored in it. The portal's hierarchy is displayed in a 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, javascripts 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 we can see the page name (this also indicates if it's a standard or built-in page) and a button to add a new element to the content (page, layout, partial, section, file, portlet). Below we can choose the layout which the page will be using, and you can also toggle the liquid tags functionality. The following part is the text editor, supporting code highlighting, tabulations, line numeration and much more. The tab buttons ‘Draft’ and ‘Published’ switch between the Draft and Published version of the edited document. The following 2 icons list the document’s versions and open a pop-up edit window respectively.

To edit page content, you just choose the desired layout, set a few additional options like content type and the 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 if you want to preview the published or the draft version of the page. Clicking the button redirects you to the CMS mode. In this mode 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 page, layout and partials edit views (this we will cover in the next section of the guide) of the CMS. Furthermore it allows you to swtich between the Draft and Published views.

Another feature of the Content section, which applies also to the next parts of the guide, is the Filter. It is not only a search field, but it also allows to limit the elements shown to only stylesheets, javascripts or any other types specified.

These sections manage the templates and the reusable parts of the page. Their functionality is similar, so we will cover it in the same step.

Layouts section consists of definitions of the templates used by pages. Layout is the main structure of the page and what is contained within this template will be rendered on every page that uses it. Inside it normally reside all the partials, portlets and the actual pages content.

Partials on the other hand are the reusable parts of code, which repeat in many places/pages (e.g. footer, which is the same on every layout, sidebar which is the same on a few pages with different layouts, etc.). To include a partial in a layout/partial/email template/portlet type: {% include "partial_name" %}. For full reference of liquid tags check here

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

  1. Text editor for the Layout template.
  2. Save draft, publish current version and revert to the last published state.
  3. Switch the Text editor between the Draft and Published versions, list the version history and launch the pop-up editor

The last subsection of the Content part are the portlets. They give you some more advanced functionality to hand without the need of any advanced coding. Our CMS provides now 3 different portlets:

  • External RSS Feed - fetches the RSS feed from a given source
  • Table of Contents - generates the links list for the pages in given section
  • Latest Forum Posts - generates the list of the n latest forum posts

While creating the desired portlet you have to input the requested data in the setup page (e.g. Title, system name and the url feed for the External RSS Feed portlet).

The Editor will come pre-filled with the standard portlet's code using some custom liquid tags. You can try editing the generated structure, but be careful and in any doubts just leave the code as it is or refer to the Portal Formatting Tabs reference

The last elements of the CMS are Redirects and Changes sections. They are much less complicated than the Content section, but also provide an important part and give some custom functionality.

Redirects help you set up redirects of some portal url to other ones. Useful i.e. when you deprecate some old page and dont want to change all the links. Note that redirects cannot be used for the CMS built-in pages, they are only meant to be used with pages created by you.

The 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 whether to publish them selectively or all at once.

In this guide we will try to explain to you what liquid formatting tags are and how they work specifically in the 3scale system. We will explain the different elements of the markup, the connections between them and short examples on how to use them in your portal.


Liquid is a simple programming language used for displaying and processing most of the data from the 3scale system available for providers. Liquid was originally developed by shopify and is used in many other CMS engines throughout the web. At 3scale we use it to expose the server side data to users, greatly extending the usability of the CMS while at the same time keeping security at a high level.


Liquids are mainly used to fetch and display server-side data on your Developer Portal's pages. However there is much more power in liquids than just this. They serve very well for:

  • altering the DOM and the content of a page based on server-side data
  • adding logic to the pages, layouts, partials
  • manipulating the e-mail templates sent to the users

There are also some use cases where liquids don't provide the best solution to the problem and those include mostly situations where you need to use some dynamic data (input from the user, the page url, etc.).

Some general advice is to use them as the primary way to add logic to the page and then, when you find it impossible or over complicated, to switch to Javascript (or add them to it, as liquids also work well with js).


Liquid markup is divided into two different types: logic tags and output tags. The logic tags, marked as '{% %}', are conditional liquid statements that include the standard programming language elements such as the if clause, loops, etc. :

Output tags, marked as '{{ }}', on the other hand are used to display the value of the tag between the curly braces.

For documentation on the logic tags, please refer to the Shoppify tutorial. The full reference of the 3scale liquid output tags can be found both on our support portal as well as in your account's admin's console under Help->Liquid Reference.

Liquid drops, tags and their meaning

In the 3scale CMS system you will have access to 3 different types of liquid markup:

  • liquid drops (e.g. {{ }})
  • liquid tags (e.g. {% content %})
  • filters (e.g. {{ form.errors.description | error_class }})

As you can see, they are almost the same as the logic and output tags and in fact work very similarly. Liquid drops are the most basic structure and you will be using them most of the time. They give access to certain values stored in the system (such as the name of the user, the id of the application, etc.). They are handled by the interpreter in the same way as any other output tags.

Liquid tags, on the other hand, are a type of logic tag which render or access certain parts of the system for further customization (e.g render content in the layout, customize email templates, etc.)

Filters, as the name suggests, enable the option of filtering results from the drops, convert values, group by some key, etc. There is a group of standard liquids filters (which you can find on the shopify website) and a group of special 3scale internal filters which are listed on the reference page mentioned earlier.

The context

The context describes which variables(drops) are available to use on the current page. The basic set includes the following variables:

  • provider
  • urls
  • current_user
  • current_account
  • today

Those variables are available on every page throughout the CMS (except for email templates). However, most of the built-in pages will have some additional variables available, for example the edit user form will have a user variable exposed (instead of current user, as on edit user page the identity of the user is already known). To check which variables are available on the current page we have prepared a special tag {% debug:help %}. It adds the list of all the top-level variables available to use as a comment in the source of the page.


The direct consequence of the context is that the liquid drops are organized in a hierarchical structure. The available set of variables only gives you the list of the top level drops which are available. Using them you can get access to elements much deeper inside the hierarchy. For example if you would like to show the username of the logged-in user you would write {{ current_user.username }}.

Displaying lower level drops is a little bit more complicated. Let's assume that you would like to display the name of the only application for a user. Looking at the reference guide, you can see that the method "applications" is a part of the account drop. This means that "applications" is an array of single application tags. If your users are allowed to have more than one application, then you would have to iterate through them using the logic tags. Otherwise you can refer to the first (and only) application in the account. The code to display that would look like this: {{ }}.

Enabling Liquids

Liquid markup processing is by default enabled for all the partials and email templates. Enabling them on Layouts is done by simply checking 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 CMS built-in editor will add code highlighting for liquid also.

Different use on pages, partials and layouts

The use of liquids usually differs slightly between pages which are single-use elements and partials/layouts which are the reusable elements of your portal. This means that, instead of using multiple layouts or partials with small changes for use on different pages, you can add some logic liquid tags inside and alter the layout depending on the page the user is on.

Use with CSS/JS

Liquid markup doesn't just work with HTML, you can easily combine it with CSS and/or Javascript code for even more control. To enable liquid in a stylesheet or js, you will have to create them as a page and follow the same steps as if you were enabling it for a normal page. Having done that, you will be able to add some conditional markup in CSS or use the server side data in javascript. Just remember to set the content type of the page as CSS or JS.

Differences from CMS

As previously mentioned, liquid tags can also be used to customize the email templates sent to your users. All the general rules on writing liquid mentioned before also apply to the email templates, with some exceptions:

  • there is no commonly shared list of variables which are available on every template. Instead you will have to do some testing using the aforementioned {% debug:help %} tag
  • because emails are by nature different than web pages, you will have no, or limited access to some tags e.g. {{ request.request_uri }} will not have any sense anymore, as email does not have a URL

For more information on configuring email templates refer to our Customize Email Templates guide.



If something is not working as intended (but saved correctly) check if:

  • all the tags are closed correctly
  • you are referring to variables available on the current page
  • you are not trying to access an array (i.e. current_account.applications is an array of applications)
  • the logic is correct

typical errors and ways to solve them

  • If the document cannot be saved due to a liquid error, it is usually because some tags/drops were not closed correctly. Check if all your {% and {{ tags were properly closed as well as whether the logic expressions (if, for, etc. ) were terminated correctly (with endif, enfor, etc.)
  • If everything saved correctly and you don't see any effect, check that: you are not referring to an empty element; you are not using a logic tag to display content ({% %} will never render any content, besides usage in tags which is already an alias of a more complex set of tags and drops)
  • If, instead of what you wanted to see, only a # is displayed, it means that you have tried to display an element which is an array. Check the section on the liquid hierarchy in this article (link)

Answers on the forum

If you still have a problem, try looking for an answer on our forum. Or ask it yourself.

The content of all standard email communication with developers can be completely customized. This allows you to closely match the workflows which you have selected for your portal.

At the end of this section you will edit and save a custom email notifications.

There are a lot of potential email templates. However only a subset of them are likely to be relevant for your environment, depending on how you have setup your workflows. You can save yourself time, by making sure you are happy with your workflows, before you begin the task of editing the email templates. This way you only have to edit the templates that you will actually use.

Perform a dry run of your finalized workflows, making sure to test all the possible branches (e.g. approval and rejection). Then identify each email notification that is received by your test developer account in the dry run, and make the edits in the next step.

Notice that all the email templates differentiate whether they are notifications for your developers (or “buyer”), or for the admins (of your API “provider” account).

HowTo portal email templates

The first time you edit a template, you will actually “create” a custom template. Then in subsequent edits, you “save” your changes. Warning: there is no version control. It is recommended that you make a local copy if you want to be able to revert changes.

Liquid tags can also be used for dynamic content in your email. It is especially recommended to make backups when you make changes to the liquid tags.

HowTo portal email template edit

Complete these same steps until you have covered all the possible branches for your workflows.

Normally you probably do not need to customize notifications to your own admins. However in larger organizations you may want to complete these additional steps. This can be used to provide instructions on what actions to take, in the context of the notification. The steps to customize these emails are exactly the same as for your developer emails.

  • Before customizing your email templates, it is best to have the signup workflows fully finalized and tested.
  • If you intend to change any of the liquid tags within the email templates, be sure to read up on the liquid reference documentation

As a provider, you will probably want to customize the email templates to use your own corporate "language" and terminology. However, you will probably also want to take advantage of the liquid drops available to you to display personalised information for each of your customers.

Similar to liquid drops in the CMS, every email template will have their own context. This means that liquid drops available in one email template, may not necessarily be available for other email templates.

With this handy reference, we aim to outline which liquid drops are available where.

We can group these email templates by subject matter and the set of liquid drops that they support.

The following email templates fall under this category:

  • Buyer Account confirmed
  • Buyer Account approved
  • Buyer account rejected

For which you can use the following liquid drops:

  • user => User
  • domain => String
  • account => Account
  • provider => Provider
  • support_email => String

Additionally the following 2 templates

  • Password recovery for buyer

have access to the following liquid drops:

  • user => User
  • provider => Provider
  • url => url

And the email to invite additional users to an account

  • Invitation

has access to:

  • account => Account
  • provider => Provider
  • url => url
  • Credit card expired notification for provider
  • Credit Card expired notification for buyer

You can use the following liquid drops

  • user_account => Account
  • account => Account
  • provider_account => Provider
  • provider => Provider
  • Alert notification for provider (>= 100%)
  • Alert notification for buyer (>= 100%)
  • Alert notification for provider (< 100%)
  • Alert notification for buyer (< 100%)

Has access to:

  • application => Application
  • account => Account
  • provider => Provider
  • service => Service
  • alert => Alert

The following email templates all deal with Application and Application Plan notifications.

  • Application created for provider

Has access to:

  • url => url

The Application Plan Change Request notification email templates

  • Plan change request for buyer
  • Plan change request for provider

have access to:

  • application => Application
  • provider => Provider
  • account => Account
  • user => User
  • plan => Plan
  • credit_card_url => credit_card_url

Finally, the following email templates have an increasing number of available liquid drops, starting with the base for

  • Application plan changed for buyer
  • Application plan changed for provider
  • Application trial period expired for buyer

which have access to:

  • provider => Provider
  • account => Account
  • user => User
  • plan => Plan

As well as all of the above liquid drops, the following Application Plan messages

  • Application suspended for buyer
  • Application accepted for buyer
  • Application rejected for buyer
  • Application contract cancelled for provider

have the additional liquid drops listed

  • application => Application
  • service => Service

And yet more liquid drops accumulate for the following email templates for Application Keys

  • Application key created for buyer
  • Application key deleted for buyer
  • key => key

The following email template

  • Review invoices prior to charging for provider

has access to:

  • provider => Provider
  • url => String

Additionally, the following templates:

  • Invoice charge failure for provider without retry
  • Invoice upcoming charge for buyer
  • Invoice charge failure for provider with retry
  • Invoice charge failure for buyer without retry
  • Invoice charged successfully for buyer
  • Invoice charge failure for buyer with retry

share the following liquids:

  • account => Account
  • provider => Provider
  • cost => cost
  • invoice_url => invoice_url
  • payment_url => payment_url

The following email templates

  • Service contract cancelled for provider
  • Service trial period expired for buyer
  • Service plan changed for provider
  • Service contract suspended for buyer

have access to:

  • provider => Provider
  • account => Account
  • user => User
  • plan => Plan

As well as the above liquid drops, the following Service templates,

  • Service created for provider
  • Service accepted for buyer
  • Service rejected for buyer

have the additional liquid drops listed:

  • service => Service
  • service_contract => Contract
  • subscription => Contract

The following email templates

  • Sign-up notification for provider
  • Sign-up notification for buyer

have access to:

  • user => User
  • provider => Provider
  • url => activate_url

There are some elements, which are generated by the system and are not possible to change from the CMS. These include the Signup, Dashboard, and Account pages. This guide will show how to customize the content on these pages with some simple CSS/Javascript scripts.

By the end of this section you will be able to modify and/or hide any elements on the system generated pages.

The 3scale system generated pages are subject to change (although infrequently). These changes may break any customizations that you implement following this guide. If you can avoid using these hacks, please do so. Before you continue please be sure that you will be able to monitor for any disruptive changes, and do the necessary maintenance work to keep your portal functioning correctly.

The first and most important thing to do is to identify what we actually want to hide. To do that, we will use Firebug (or you can use any other Developer tools, like Chrome Developers tools, Opera Dragonfly, etc.). Let's choose the desired element and then in the console right click on it and select "Copy CSS path". This way we will have saved the exact CSS path in order to make it easy to manipulate. Remember, that if the element is a part of the sidebar navigation widget, you will also have to specify which position in the list. For this you can use either the "+" selector (e.g. to choose 3rd li element: ul + li + li + li) or the ":nth-child(n)" CSS3 pseudoclass.

HowTo portal modify 3scale system pages css

Now, having identified our elements we can change their display settings. Depending on the type of element we can choose from two possible methods: CSS manipulation or jQuery script. The first one is more lightweight and reliable, but doesn't work well for some kinds of elements, which exist on a number of pages (e.g. 3rd element in the Dashboard's sidebar also exists in the Account section, but has a different value) and some more tricky implementations require use of CSS3 which is not supported by old browsers. In the next two steps I will show you both of those approaches.

As an example lets try to hide the Latest Forum posts box from the Dashboard page. Following the first step, we have identified its CSS path as: We have to keep in mind, that it is the second box with the same path, so we will use the "+" selector. Our path will now look like this: Changing display property to none we make that box invisible:

If we have a more tricky element to hide, like a sidebar menu element, it is better to use some jQuery. This is because the CSS path of these elements is identical on the Dashboard and Account sections, and we don't want to hide elements in both sections. So we will choose the element based on the CSS path and the content. In this example let's assume, we want to hide the messages section from the Dashboard's sidebar. Our CSS path is: In order to match the content we will use the .text() function. We will also include the code inside the document's head and inside the ready function, so it is executed after all the content has been generated.

HowTo portal modify 3scale system pages
The resulting code snippet will look like this:

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

If you are using the multiple services functionality, you are able to customize the signup procedure to allow customers for subscribing to different services.

By the end of this section you should be familiar with the procedure to create and customize a multiple service signup page.

You should be familiar with layout and page creation procedures as well as with the basics of Liquid Formatting Tags. You can check our Liquid Tags reference here. Moreover "Multiple Service" functionality must be enabled on your account (available from Pro plan and upwards)"

We strongly recommend reading about the Signup Workflow, so you will have all the setup prepared and be also aware of how it works.

We will start the process with creating a new Layout, which will serve as the template for our multi-service signup page. Let's go in the Layouts section in our CMS system and create the new Layout. We can call it: multiple_service_signup, to easily distinguish it from the other layouts, and in the editor paste the general structure of your standard layout (e.g. home or main layout). Now delete everything which we wont need for the signup (e.g. all the containers, sidebars, additional boxes, etc.).

Having created this backbone of our layout, we can proceed to customizing the code for signup.

In order to retrieve all the informations about the services, which we need to construct the proper signup link, we have to loop through the service objects. Services are a part of the model object.

We already have our layout and loop accessing the service objects. Now we should decide the way we want to display the service's informations and the signup link. I have decided to divide them into columns with a service description and a Signup link in the bottom. Every column will be a div box with a 'service-column' class and containing all the necessary informations.

The container inside serves as a custom description field and is the service name, which in this case will be the containers name.

Now we come to the main part of our custom service signup. To create the signup link we have to extract the signup url and the service id. The first we take from urls object, and the latter from our service object on which we iterate in the loop. The final link code will look like this:

We also have to take into account that the user may already have signed up for some of our services. To check that, lets create a conditional block.

With this we can generate the final code:

Let's add some final touch to the generated markup. This depends on the amount of services we have. In my case it's two, so the CSS code for the 'service-column' div will be:

We have used the percentage based layout to dynamicaly assign the width of the column basic on the containing div's dimensions.

Now you should have properly working and properly looking multiple service subscribe page. Congratulations!

If you would like to display the columns in a specific order, you should try using the conditional expressions (if/else/case) conditioning the service name or other value, which you know.

Sometimes you might need to have some pages of your developer portal only accessible for a group of developers. It may also just be a part of a page or even some items in a certain menu. Both goals are achievable through the two techniques introduced below.

Here you will learn how to have content in your developer portal that is only visible for some users.

When creating restricted sections it is often useful to do it in a way that each section maps to a logical group of your users. For this example we will assume that there is a group of developers we call "partners".

For every page or group of pages that you want to restrict access to, you should create a new section in the CMS. Uncheck the "public" status field. Then drag and drop any pages you want inside this section.

creating a new private section

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

creating a new group

Now every time you have to grant one of your users access to this section you will only need to assign him to this group. The way to do that is to go into the corresponding account detail page, then to "Group Permissions" and once there check the boxes for the sections you want to allow.

group permissions screen

Liquid tags are a very powerful way of customizing your developer portal. We will use them here to hide or display parts of a page based on a condition. 3scale allows creating custom fields for accounts, applications or users. You can leverage this ability to store information that is useful for you as the API provider. Here we will create an custom field attached to all accounts, and we will use it to indicate if a given account is a "partner" or not. You can create such field going to "Settings" > "Field Definitions". Add a field to the Account section and mark it as hidden so it will not be displayed on the sign up page or anywhere else on the portal.

field definitions screen

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

or using the inverse logic, if it suits your case best:

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

In many cases you might want to provide access to restricted content to a developer based on some change in his state. For instance, when he upgrades his application plan.

A way to streamline the process would be to use webhooks together with the account management API. Based on the plan the developer has switched to (which can be known from the message sent by the webhook request) you can grant him access to the private content by calling the API to update the "partner" field.

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

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

This article shows how existing user credentials of your web site can be used to automatically login to the 3scale-powered Developer Portal.

Single Sign-On (SSO) allows you to manage access control of multiple independent systems. By following this guide you will be able to allow users that are logged in in your system to log-in automatically to your 3scale-powered Developer Portal without being prompted to log-in again.

This feature is meant for those API providers that already own the identity of their API consumers (username and password) i.e. the API provider is also the Identity provider.

First of all, the API consumer must have an account in your 3scale-powered Developer portal. You can import your users to 3scale using the Account Management API or create them manually.

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

There are 2 parameters in this call: username to specify for whome you are requesting the token and expires_in which is the number of seconds that the token will be valid for and 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:

NOTE: You can pass either user_id OR username to identify the 3scale user. Typically, the username will be the same for your system and 3scale Portal. In that case using the username should be easy as it does not require any additional information to be stored on your side. If you however need to do some pairing and machine processes the URLs anyway, you might be better off with user_id.

The response contains an SSO log-in URL with a token:

The URL contains all the required information for the 3scale Developer Portal SSO to log you in and you can embed it directly into web. Bear in mind however, that the URL can expire before user clicks it. It is therefor 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 into your 3scale-powered Developer Portal.

The URL needs to be unescaped. If you want to try it by hand in a browser or cut and paste, remember to replace the "&amp;" for "&" in your browser. Also any "%" encodings in the token need to be replaced by their unescaped character

This article will show you how to enable and disable the different types of authentication that can be made available on your developer portal to allow your developers to sign up or sign in.

At the moment we support 3 different ways of authenticating to the developer portal and we will walk you through these in the following sections:

  1. Username/email and password
  2. Authentication via GitHub
  3. Authentication via Auth0

By default, two types of authentication will be enabled on your developer portal:

  • Username/email and password
  • Authentication via GitHub (using the 3scale GitHub application)
GitHub Authentication

After following these steps you will have configured the access to your developer portal.

Older 3scale accounts (created prior to December 14th, 2015) might need to follow an extra step in order to enable GitHub and Auth0 authentication.

If this applies to you then the following code snippet will need to be added to the Login and Signup templates in order to enable this feature in both forms.

{% include 'login/sso' %}

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 occasions you might want to remove this authentication type; please edit the Login > New template as in the screenshot below:

Portal Authentication Snippet

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 you will need first to create one and retrieve the corresponding credentials.)

By default, authentication via GitHub will be enabled on your developer portal along with the username/email and password authentication.

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

  • Using the 3scale GitHub application (enabled by default)
  • Using your own GitHub application (available on Base plan and above)

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

SSO Integration

Click on “GitHub” to access the configuration screen:

SSO Edit Integration

From this screen you can:

  1. Make the GitHub authentication available or not on your developer portal
  2. - To make the GitHub authentication available or not on your developer portal, you just need to check or uncheck the “Published” box

  3. Choose the 3scale branded GitHub application or add your own GitHub application
  4. - By default the 3scale GitHub application is enabled (published) but you can enable your own GitHub application by clicking on “Edit” and entering the details of your GitHub application (Client and Client Secret).

  5. Test that the configured authentication flow works as expected
  6. - This feature will allow you to test that your configuration works as expected.

This feature is only available to the Enterprise plan.

(In order to use Auth0 to have your developer authenticate, you will first need to have a valid Auth0 subscription.)

Authentication via Auth0 won’t be enabled by default on your developer portal. If you want to use your Auth0 account in conjunction with 3scale to manage the access to your developer portal, you can follow these steps to configure it:

Go to your 3scale admin portal, in Settings > Developer Portal > SSO Integrations and click on “Auth0”.

SSO Auth0 Authentication

In this configuration screen you will need to add the details of your Auth0 account. Once you have entered the client Id, client secret and site, check the “Published” box and click on “Create Auth0” to make it available on your developer portal.

It is increasingly common to see businesses charge for access to their APIs. Sometimes the entire business model of a company is built around Paid APIs, while other times it is an important revenue stream to cover costs or generate profits for the company.
This HowTo will help you define a great workflow in your Developer Portal to ensure that developers submit their credit card details before they gain access to your Paid APIs. * 3scale Finance module (Billing and Charging) activated and configured * Paid plans defined (usually Application Plans)
Place this snippet anywhere you like on your home page, and style it as desired with CSS. Note that this notification will not show for any free plans, nor if charging has been disabled for the current account:

It is through the API Credentials that the developer gains access to their keys to start making calls on your API. Here we make sure that we only display the link if there are no paid plans or if the credit card is available when necessary. If you want to be completely strict about this you will edit the system page for displaying the keys to restrict the display, but this would be an advanced customization. You may also want ot delete the snippet to display credentials directly on the home page after log in

The API Credentials menu item is displayed as the left-most menu item after signing in with the default portal.

This HTML is normally controlled with the submenu partial. Edit the references to display the link to API Credentials with the following snippet:

You may find it easier to refactor the menu display rather than to cater for all the complex options in the default portal. For example you can eliminate the step to create a new application, and instead within href="/xxxx" only display either: app.url for a single app, or urls.applications for multiple applications

You may allow developers to select plans when changing plans. The ideal setting is to "Request Credit Card entry for paid plans". This will ensure that if a paid plan is selected, the plan change can only be done instantly if a credit card is stored. Otherwise a notification is displayed to point the developer to the location to enter their card details.

This setting is defined from the admin console: Go to >API>Service(select)>Settings>Application Plan Changing. Here you can select the option "Request Credit Card entry for paid plans".

By default 3scale provides commonly used fields at User/Account/Application signup. You may need to add your own custom fields to these common defaults.

Here you will learn how to add custom signup fields and the different options around this facility.

In your Admin portal, go to "Settings" > "Field Definitions". Here is where you see the defaults and can define new ones:

field definitions default fields

The new Account/User signup screen is actually an amalgamation of the first 2 sections. The Account fields appear at the top followed by the User fields, followed by the password fields which don't need to be configured.

new user sign-up default

Now let's add 3 extra fields; 2 to the User signup section, 1 to the Account section. Click Create and add the following new field definition and then Create it. The Required checkbox will obviously make it mandatory on the Signup form. Other self explanatory options are Hidden and Read only
A hidden field may be added for example when you want new signups to have fields set that you don't necessarily want to highlight to them, e.g. access_restricted_areas which would be empty by default. As an Admin you could update this to true later on a per user basis. Your page logic could read it in to determine what to display.
A read only field might be for example browser locale, which you could use Javascript on page load to set.

new last name

Now let's add a Drop Down to the user Signup form. Let's call it Employment Type. Add these comma separated values into the Choices field: Full Time, Part Time, Contract. The drop down will be populated with these values.

new drop down

Now let's add a Pre-Defined field to the Account. Normally the fields you add have no System functionality - they simply hold data which you can access later. See Restricted content

As normal, create a field then on the drop-down above Name, choose po_number. With this field, when 3scale generated invoices, this PO Number will appear on invoices sent from 3scale to this Developer Account. These system generated fields can be overridden by your admins at any time.

Now give the field a name something like PO Number. Create it.

new pre defined

Now let's take a look at our work. We can see the free text Last Name and the Employment Type drop down have been added to the User section. The PO number system field, also free text, has been added to the Account section.

signup with new fields

Finally, these custom fields can be set using the 3scale API, e.g. Application Create on 3scale API

HowTo write in Textile