Basics

In order to share the workload of administering your APIs you may wish to invite colleagues from your organisation to access the 3scale dashboard and assign them rights to different areas such as technical documentation, finance or developer administration.
This feature is available on enterprise accounts only.

At a end of this how to you will have given admin access to the 3scale API console to one or more colleagues.

On the main administration panel click on the Account button on the top right hand side and select Users from the submenu

Admin Users: These users can access the 3scale administration panel for the API.

From the menu select the Invite New user button.

Enter the email address of the colleague to invite. Putting an email in the invitation box and clicking send, will send an invitation email to the colleague you wish to invite (check spam filters if the email does not arrive).

When they receive the email, your colleague needs to click the link contained in the email and fill out their personal details in the joining form. Once saved, their account is confirmed and active. However, they will have very limited rights within the portal.

Once the account is created, the new administrator will have very limited rights within the portal. To rectify this, you can now edit the new user by selecting them from the user menu and clicking Edit.
Switching Rights to “Admin” gives full access to the control Dashboard.

 


After creating your account you need to add a little colour to it with configuration information for your own corporate logo and billing info.

At a end of this you’ll have configured your location and contact information and added you company logo to the admin dashboard.

Once your account is created, head to the Account section of the dashboard and then click on the Details edit item inside the Overview subsection. On this check or fill in the information for your account:

The address given here is used by 3scale for billing purposes if you are on a paid plan and also for invoice issuance to your users if you are using the billing/payments modules.

On the same screen you can also select the timezone you’d like to use in all system displays – the setting affects statistics graphs. Note however, that billing cycle calculations are made according to UTC time.

To change the standard logo on the dashboard to be your own, head to the settings area of the portal and use the “Logo” settings section to upload a new logo. This logo will appear on your internal 3scale dashboard but will not affect the public portal in any way, unless you will use the "logo" liquid tag for it's display (see the API Portal Configuration Section to see how to configure the public portal).


One of the most popular ways to monetize an API is by defining subscription fees for usage of the API. This section focuses on the use of application plans to provision pricing tiers. It is also possible to apply pricing rules at the account and the service level, and these topics are covered in advanced guides.

At the end of this section you will understand the pricing options for application plans and be able to setup a paid plan.

The first question is to decide how to differentiate between the tiers in your pricing model. The answer could be one of, or a mixture of:

Volume / Usage
The most common way to scale between tiers is based on volume because this is usually strongly correlated with value to customer, as well as cost to serve. You can apply this on a global hit count for calls on the API, or with more granularity at the method level
Functionality
Depending on the tier, you may enable or disable access to parts of the API. This is a good approach to distinguish standard and premium levels.
Resources
For any other resources which provider value to the customer, or are a cost driver in your infrastructure, you can meter out access. Examples are bandwidth consumption in GB, number of users, or transaction values.

Once you have decided on your pricing drivers, you need to also decide the pricing rules. The options include flat rate subscription, variable rate, and one off upfront charge. If you use volume of hits or resource consumption for your differentiation, then clearly you will have an element of variable rate pricing. All three of the pricing drivers are also compatible with the one off, or monthly flate rate subscriptions.

First you either create a new application plan or edit an existing plan. As part of the creation step you can enter any upfront charges or flat rate subscriptions.

Create new application plan or edit existing

In the edit application view, you can enter/modify the upfront charges and subscriptions. Next you setup up the pricing drivers that you chose in step 1. If some of the drivers already exist as metrics, then you simply edit the item:

  • Volume drivers: are applied at the level of the global hits metric, or for individual methods under hits. Multiple pricing rules can be applied to any metric. Note that the hits calculation is cumulated over a one month billing cycle
  • Functionality drivers: are set by enabling or disabling the metric for this plan
  • Resource drivers: are similar to volume drivers, but are applied on custom metrics
Setup pricing drivers in application plan
Zoom in to edit pricing rule in application plan

Once you are finished with setting up your pricing rules, be sure to click “update application plan”

It is fine to define an API paid plan with one single application plan. Usually this would be the case if all your pricing rules are defined with volume or resource drivers. However if you want to offer separate plans for the different segments of your developer community, you will need to add more application plans. The easiest way to do that is to copy the first application plan from the application plan overview page. This way you have a pre-populated plan with all the existing metrics and pricing rules. Of course the more care you take to create a full plan the first time, you more time you will save with the plan copy feature.

In order to provision the plans, your developers must create new applications, and select one of the new paid plans. You can also do this on their behalf from the admin console. For any existing applications it is also possible to change from an existing plan to one of the new paid plans.

In conjunction with flat-rate pricing plans it is very common to differentiate the different tiers through varying rate limits. The steps to do this are explained in Provision rate limits


Rate limits allow you to throttle access to your API resources. You can configure different limits for separate developer segments through the use of application plans.

Once you have rate limits in place, these limits will control the responses when you make authorization request calls to 3scale’s backend.

If you do not yet have an application plan defined, you should first create one. Otherwise select your plan and click “edit”.

HowTo basics appplan edit
HowTo basics new usage limit

When you are finished with setting all the limits you want, you should make sure to save your changes with “update application”.

Now that you have your rate limits defined, the following will happen:

  • If you have alerts configured, the new limits will be used to decide when notifications are sent
  • When you make authorization calls to the 3scale backend, the limits will be taken into account. If usage is above the limit, then the response is for an authorization failure. However this is a “soft” rejection, and your app ultimately decides how to handle the rejection.

Besides setting rate limits, you can also set variable pricing rules for the same metrics: Provision paid plans


To have your API portal fully branded to your look and feel you’ll likely want to have it appear under your own corporate domain name at a location like https://developer.mydomain.com or https://api.mydomain.com.

Note that this feature is only available on the Plus plans and above.

Note also that the procedure involves several approval steps – so please allow plenty of time (we recommend 2 weeks) to initiate the change before it is required.

This is part of a 3 part series on branding. See the other sections:

  1. Portal Look and Feel
  2. This how to
  3. Email Sender Configuration

At the end of this how to you will have changed the URL of your portal to a new location under your own company domain name so that you can publicize it under your own brand.

Configure your own DNS records to point to the location of 3scale’s servers.

CNAME developer.mydomain.com pointing to mydomain.3scale.net

Note developer.mydomain.com is the most popular domain among 3scale customers. You need to implement the CNAME via your DNS provider, for examples with GoDaddy and eNom see below.

Normally you will want to make the change to your custom domain before you allow public access to your developer portal. In case you already have public users, you should bear in mind that it is not possible to define a redirect from mydomain.3scale.net to your custom domain. Therefore you would need to inform your users about the domain change.

It is best to implement the CNAME in advance. In a few rare cases this is not possible such as when you have an existing site in public use at that domain. If this applies please contact 3scale support to determine the best way to synchronize a switchover

All API portals run under SSL and hence when switching to your own domain you will need to enable an SSL Certificate for your domain. Inform 3scale with the following information:

  1. Your company name.
  2. The domain name you would like to activate (which needs to be a domain within your control) e.g. developer.yourdomain.com

3scale will confirm the domain name procedure and initiate the creation of an SSL certificate using Digicert. As part of the process an email will be sent from the certificate provider (DigiCert) to the registered contact owner of your domain. This is often a named person in your organisation or a generic address such as postmaster@yourdomain.com*.

The email will request approval of the creation of an SSL certificate for the subdomain and the person in question will need to approve creation.

It is important before initiating the process to inform the individual who will receive the above email that this is happening.

Once the certificate is issued it will be issued to cover the portal and 3scale will confirm once this has been done.

Within a maximum of one week after receiving the SSL certificate approval, 3scale will complete the domain switch in our systems and will inform you.

The DNS records need to propagate before users start to be able to associate the new location with this address. This normally takes about 30 mins, but can take up to 24hrs. If it takes longer than this, check that the record has been correctly associated with the domain. You can do this by using a tools such as nslookup or dig on the subdomain.

Review and test your portal carefully after the domain change. In particular:

  1. any ActiveDocs will require an update to reflect the new domain
  2. any links to the custom domain which are not relative must be updated

This section provides instructions for making the DNS change using various popular registrars.

  1. Log in to your account at http://www.godaddy.com by navigating to the My Account tab.
  2. Under the Domains section, find the domain you wish to use for the developer portal and click Advanced Details on the domain.
  3. In the DNS Manager section, click Launch.
  4. Select Quick Add In the CNAME section.
  5. In the new entry, enter the following information:
  • Host: enter the name of the subdomain you plan to use for the CNAME, e.g. if you want to use “developer.mydomain.com” then enter “developer”.
  • Points to: Enter yourdomain.3scale.net.
  • TTL: Leave the TTL value at the default value.

At the top or the bottom of the page, click Save Zone File, followed by OK in the pop-up. Your CNAME should now be configured – bear in mind that it may take 24hrs for the records to propagate.

Log in to your account at www.enom.com.

  1. Log in to your account at http://www.enom.com.
  2. From the menu at the Domains tab, select My Domain to get to the Manage Domains page.
  3. Find and click the domain you wish to use for the developer portal and click Advanced Details on the domain.
  4. Click Host Settings.
  5. Click on NEW ROW and enter the name of the subdomain you plan to use for the CNAME, e.g. if you want to use “developer.mydomain.com” then enter “developer”.
  6. For the Host Name enter yourdomain.3scale.net.
  7. Click Save.

Your CNAME should now be configured – bear in mind that it may take 24hrs for the records to propagate.


Emails sent by the 3scale system to developers on your behalf, are distributed by the service provider, Sendgrid. The configurations guidelines in this section allow the emails to come from one of your domains rather than from 3scale.

This feature is not available on Base plan accounts.

After you have configured the email setup on your side, then inform 3scale support (support@3scale.net) for the remaining step to be completed.

Just as for SSL certificates, it is recommended to complete these steps as soon as possible.

email config figure

  1. Add a domain that is a CNAME to Sendgrid. Example (choose anything you like for the “APIMAIL.YOURDOMAIN” subdomain):
  2. APIMAIL.YOURDOMAIN.com CNAME sendgrid.net
  3. Add the following TXT record:
    v=spf1 a mx include:sendgrid.net ~all
    (or add “include:sendgrid.net” to an existing record)
  4. Add the domain keys to ensure email deliverability:

Use the following DIG statements from the command line to verify that your DNS changes are correctly implemented:

As the final step, inform 3scale support to initiate the email change with the following information:

  • Desired email address for outbound mail. The email address should be of the form “apicontact@YOURDOMAIN.com”.
  • Entry that you used for “APIMAIL.YOURDOMAIN
  • Full company address (including country)
  • Contact phone number