Basics

In order to share the workload of administering your APIs, you may wish to invite team members from your organization to access the 3scale dashboard. You can assign rights to different areas such as technical documentation, finance, or developer administration.

We’ll walk you through how to give admin access to the 3scale API console to one or more coworkers.

Note: This feature is available on enterprise accounts only.

On the main admin panel, click on the Account button on the top righthand side. Select Users from the submenu.

Admin users are users who can access the 3scale admin panel for the API.

From the menu, select the Invite user button.

Enter the email address of the person you want to invite and click send. An invitation email will be sent to the address you entered. If the email doesn’t arrive, make sure it didn’t get marked as spam.

Your new administrator must click the link in the invitation email and complete the subsequent form to complete the process. Once the form is submitted, their account will be and activated. However, they will have limited rights within the portal.

To give your admin full rights, edit the new user by selecting them from the user menu and clicking Edit.
Changing their rights to “admin” will give them full access to control the dashboard.

 


After creating your account, update basic information about your company. Set your location, contact information and add you company logo to the admin dashboard.

Once you’ve created your new account, head to the Account > Overview section of the dashboard. Then click Edit on the Details item. Fill in the information for your account.

The address you write here is what we use for billing purposes (if you are on a paid plan) and also what your user will see on your invoices if you’re using the billing and payments modules.

On the same page you can also select the time zone you’d like to use on all system displays. This setting affects analytics graphs. However, billing cycle calculations are made according to UTC time.

To change the standard logo on the dashboard, head to the settings area of the portal. In the Logo section, upload a new file. This will be the logo that appears on your internal 3scale dashboard, but it will not affect the Developer Portal in any way, unless you use the "logo" liquid tag or its display (see Developer Portal Configuration).


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

Below you’ll learn about the pricing options for application plans and how to set up a paid plan.

The first decision to make is how to differentiate between the tiers in your pricing model. Will the tiers be driven by by volume/usage, API functionality, access to other resources, or a combination?

Volume / Usage
The most common way to differentiate between tiers is based on volume because volume usually has a strong correlation to value to the customer as well as cost to serve. You can apply a global hit count for calls on the API or a more granular measurement at the method level.
Functionality
You can enable or disable access to parts of your API depending on the tier. This is a good approach to distinguish between standard and premium levels.
Resources
You can also create tiers based on access to any other resources that provide value to the customer or drive costs in your infrastructure -- for example, GB’s of bandwidth consumed, number of users, or transaction values.

Once you have decided on your pricing drivers, you must decide whether the tiers will be based on a flat rate subscription, a variable rate, or a one-off upfront charge. All three of the pricing drivers above are compatible with the one off, or monthly flat rate subscriptions. If you decide your pricing will be based on volume of hits or resource consumption, there will of course be a variable element to your pricing.

You can either create a new application plan or edit an existing one. When creating a new application plan, 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 or modify the upfront charges and subscriptions.

Next, set up the pricing drivers you decided on in step 1. If some of them already exist as metrics, you can 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’re finished setting up your pricing rules, be sure to click “update application plan”.

It’s ok to define an API paid plan with a single application plan. Usually this would be the case if all your pricing rules are defined by volume or resource drivers. However if you want to offer separate plans for different segments of your developer community, you’ll need to add more application plans.

The easiest way to do this is to copy the first application plan from the application plan overview page. This way, it will be pre-populated with all the existing metrics and pricing rules. The more care you take to create a full plan the first time, the 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’s also possible to change from an existing plan to one of the new paid plans.

In conjunction with flat-rate pricing plans it’s common to differentiate between tiers using rate limits. This is 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 a developer receives when they make authorization request calls to 3scale’s backend.

If you don’t have an application plan defined yet, create one first. Otherwise, select the plan you want to set rate limits for and click “edit”.

HowTo basics rate limits
HowTo basics new usage limit

When you’re finished setting the limits you want, make sure to save your changes by clicking “Update Application plan”.

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.

Once your rate limits are operation, you’ll see the users that are reaching the limits on your dashboard, making it quick and easy to check for potential plan upgrade candidates.

HowTo basics dashboard messages

Besides setting rate limits, you can also set variable pricing rules for the same metrics -- see provision paid plans


To complete the branding of your Developer Portal, you’ll probably want to have it appear under your own corporate domain name at a location like https://developer.mydomain.com or https://api.mydomain.com. The most popular option among 3scale customers is developer.mydomain.com.

This process involves several approval steps, so please allow plenty of time (we recommend 2 weeks) to initiate the change before you need it to be done.

At the end of this tutorial, you’ll have changed the URL of your Developer Portal to a new location under your own company domain name.

Configure your own DNS records to point to the location of 3scale’s servers. You need to implement the CNAME through your DNS provider.

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

Normally you would want to make the change to your custom domain before you allow public access to your Developer Portal. If you already have public users, bear in mind that it’s not possible to define a redirect from mydomain.3scale.net to your custom domain, so you’ll need to inform your users about the domain change.

It’s best to implement the CNAME in advance. In the rare case that this isn’t possible -- such as if you have an existing site in public use at that domain -- please contact 3scale support to determine the best way to synchronize a switchover.

All Developer Portals run under SSL. When changing to your own domain, you’ll 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 such as developer.yourdomain.com (this needs to be a domain within your control)

3scale will confirm the domain name procedure and initiate the creation of an SSL certificate using DigiCert. DigiCert will send an email to the registered contact owner of your domain requesting approval of the creation of an SSL certificate for the subdomain. The person in question -- either a named person in your organization or a generic address such as postmaster@yourdomain.com -- will need to approve it.

Before initiating the process, it’s important to inform the individual who will receive the email that this is happening.

Once the certificate is approved, it will be issued to cover the Developer Portal. 3scale will confirm once this has been done.

Within one week (maximum) after receiving the SSL certificate approval, 3scale will complete the domain change in our systems and inform you.

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

Review and test your Developer Portal carefully after the domain change. In particular, any links to the custom domain that are not relative must be updated.

This is part of a 3-part series on branding. You may also be interested in:


Emails sent from the 3scale system to developers on your behalf are distributed by 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 Personal plan accounts.

After you have the email setup configured on your side, inform 3scale support (support@3scale.net) to complete the process. Just as for SSL certificates, we recommend you complete these steps as soon as possible.

email config figure

  1. Add a domain that is a CNAME to SendGrid. (Choose anything you like for the APIMAIL.YOURDOMAIN subdomain):
  2. APIMAIL.YOURDOMAIN.com CNAME u11705.wl.sendgrid.net
  3. Add the following TXT record to YOURDOMAIN.com:
    v=spf1 include:u11705.wl.sendgrid.net -all
    (Or add include:u11705.wl.sendgrid.net to an existing record.)
  4. Add the domain keys to ensure email deliverability:
  5. s1._domainkey.YOURDOMAIN.com CNAME s1.domainkey.u11705.wl.sendgrid.net
    s2._domainkey.YOURDOMAIN.com CNAME s2.domainkey.u11705.wl.sendgrid.net
    o1.APIMAIL.YOURDOMAIN.com A 75.126.253.120

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

dig cname APIMAIL.YOURDOMAIN.com
# should return "u11705.wl.sendgrid.net"

dig cname s1._domainkey.YOURDOMAIN.com
# should return "s1.domainkey.u11705.wl.sendgrid.net"

dig cname s2._domainkey.YOURDOMAIN.com
# should return "s2.domainkey.u11705.wl.sendgrid.net"

dig a o1.APIMAIL.YOURDOMAIN.com
# should return "75.126.253.120"

dig txt YOURDOMAIN.com
# should return "v=spf1 include:u11705.wl.sendgrid.net -all"

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 in the form of apicontact@YOURDOMAIN.com.
  • Entry that you used for APIMAIL.YOURDOMAIN.
  • Full company address (including country).
  • Contact phone number.