One of the most common things you want to do when opening up your API is set access policies for users to ensure everybody gets fair use and system resources aren’t threatened with overuse. Often it also makes sense to apply different policies to different groups of users – basic access for some, more liberal policies for others.

---

You can set a wide range of policies from your 3scale control panel in a few easy steps by creating plans for users to sign up to and also customize rules on a per user basis. We’ll walk through the basic steps here.

Creating your first plan

---

3scale groups policies for users together into “plans” which define a set of usage rules for a groups of users. Those rules can include both API usage limits, features and pricing rules if the API is non-free. To create a plan:

• Log into your 3scale control panel at: http://www.3scale.net/login.
• Head to the API > Plans section: http://www.3scale.net/admin/plans.
• Click on “new plan” and give the plan a name.

Configuring limits

Once you’ve set the name, you can move on to defining features and metrics – these define the level of access you want to provide to the API.

---

---

From this interface you can:

• Add new metrics to be tracked.
• Add limits to existing metrics as shown below.
• Add new methods to the “hits” metric to add limits per individual method on your API.
• Add Legal Terms & Conditions specific to the Tier you’re creating.

---

The metrics and methods you add here are also those which will be tracked by the 3scale analytics tool and are shared across all plans.

---

Limits apply only within this particular plan, with each new plan, new limits can be defined per metric and method.

Adding features to a plan

---

In addition to metrics and methods, a plan can also be configured to list “features” which are available to the developers on this plan. Features might be items such as “SSL access” or “Gold support” which are not directly measurable but might differentiate one plan from another. Features also appear in every plan you add, and can be activated and de-activated on a per-plan basis.

Publishing the plan and adding more plans

---

Once you’ve added the first plan you’ll have established the metrics, methods and features which are most important for your service. However the plan is hidden from your users until you hit publish on the plan’s control panel. From this point on the plan will be visible and users can sign up to create keys.

---

Now that you can begin to gather signups, however you may want to differentiate between different types of users. You can do this by adding as many plans as you like from the control panel – each with a different set of access policies and features activated.

Pricing Rules

If you plan to charge for your API, plans can also be used to set up tiered pricing rates for users of the API (note that you need to have the payments feature activated in your account – contact us at support@3scale.net for help on this). You can do this from the same features and metrics control panel for the individual plan:

---

---

Using price controls you can:

• Define a Setup fee.
• Define monthly recurring fixed fees.
• Define a trial period.
• Define unit costs by metric and method for monthly recurring variable fees.
• Generate invoices per developer account per month.
• Credit revenues to your own merchant account automatically.

Settings allow the definition of multiple ranges of prices for each metric/method. So for example you can provide the first 2000 transactions free on a given plan and then charge from then on or define an decreasing scale of costs.

---

Public and Private Plans

Once a plan is published it is normally visible publicly on the developer portal. However, you may wish to keep the existence of certain tiers of service hidden and only move users on to these manually. You can do this by selecting “hide” on the plans control panel – this stops the plan from appearing as an option to users but still allows you to switch users to that plan on the user control panel.

Customizing limits on a per user basis

Once you have developers signed up for different plans you have broad control of your API. However often you may need to make exceptions for specific partners for business reasons – increasing their limits, changing charging rates or some other customisation. You can do this from the users panel.

---

Click on the user you wish whose permissions you wish to edit and click “customize” – this takes you to the plan configuration to create a custom plan for this user. The limits can be modified at any time or reset back to the original base plan.

More on this topic

Hopefully this gives a useful introduction to how to configure your API policies but if you have questions, head over to the forum or email us at support@3scale.net!