Admin Portal Guide

Once you have created your new account, add you company information with these steps:

The address you specify here has two goals:

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

3scale supports single sign-on (SS0) authentication for your members and administrators.

The 3scale Admin Portal supports the following SSO providers, each which support a number of identity brokering and member federation options:

Only users that have been added to Red Hat single sign-on or Auth0 will be able to access your 3scale Admin Portal through SSO. If you want to further restrict the access by either roles or user groups you should refer to the corresponding step by step tutorials on the Red Hat single sign-on or Auth0 support portals.

Once you have established SSO through your chosen provider, you must configure it and enable it on the 3scale Admin Portal.

Once you have configured SSO, members can sign on using the account credentials in connected Identity Providers (IdPs).

Follow these steps to log in to the 3scale API Management Admin Portal using SSO:

Once you successfully sign up, you will have a member account under the application programming interface (API) provider organization, and you will be automatically logged in.

This section describes the redirection to an IdP login window via Red Hat single sign-on. As a 3scale API Management administrator, complete these steps to have your 3scale account accessible through an optional SSO login page.

To see the list of users of your 3scale installation, follow these steps in the Admin Portal page:

From the list of users, you can invite a new team member. To send the invitation:

An invitation email will be sent to the address you entered. If the email does not arrive, make sure it was not marked as spam in the recipient’s email account.

Additionally, you can find the list and status of sent invitations in Users > Invitations.

Your new administrator or member must click the link in the invitation email and complete the form to complete the process. Once the form is submitted, their account will be activated.

There are two main type of rights you can give to members of your team:

To give a new user rights, edit the new user by selecting them from the user menu and clicking on Edit. You have the following user roles:

Giving access to certain areas of the Admin Portal will give members access only to the equivalent API:

There are different types of notifications:

Admin users have access to all notifications.

Member users have access only to notifications of the areas they have been given access to. For example, a member will only have access to notifications related to billing if they have access to the billing section.

For enterprise accounts, member users will only have access to notifications regarding activity of the services they have been granted access to.

Subscriptions are personal and can only be modified by the person receiving those notifications. To edit your subscriptions:

In addition to email notifications, you can find information about the last activities in your Dashboard:

Access tokens allow application programming interface (API) provider admins and members to authenticate against the 3scale APIs - Billing, Account management, and Analytics - and try them out using our ActiveDocs.

An access token may provide either read and write access, or read only.

An important thing to take into account is how access tokens work, which is according to the member’s rights. Admins can create tokens to authenticate against all three 3scale APIs. Members will be limited by their permissions to access the different parts of the Admin Portal. For example, if a member does not have access to the Billing area, they will not be able to create a token to authenticate against the Billing API.

Access tokens can be created on the tokens page. To create tokens, follow these steps:

Note that if you are a member, you might not see all the APIs - just the ones you have been given access to by the admin of your account.

You can create as many access tokens as you need. When you create a new token, you will be alerted to save the token so you can then use it to make requests to the 3scale API.

If you lose a token, we recommend that you delete it - which will disable it and render it invalid - then create a new one.

When using your access token to make calls to the 3scale APIs the results will be filtered by the services you have access to.

For example, when deploying APIcast self-managed, you will need an access token so your APIcast API gateway can pull the configuration of the service using the Account Management API.

The way it works is if your organization has set up three services on 3scale, and as a member, you have access to Service 1, but not 2 and 3, and you also have access to the Account Management API, when you create a token and make a request to the Account Management API you will only get the applications which are using Service 1.

Following the same example, if you have access to the Account Management API, but access to zero services, when making a call, you will get an access denied error.

As an admin, you can skip even some of the required fields. If you want to invite users to the account securely, you can also skip the password fields. However the email on this main admin account must be unique among all users.

If you want to pre-configure app keys for the account, you can also add an application on behalf of the developer. Otherwise, leave this as one of the initial steps for the developer to take.

You can either send an email invitation to the developer manually or follow the steps to use the invite developer feature.

If you, as the admin, receive an email notification that one of your developers has an item pending approval, you can copy/paste the URL for the item into your browser, and it will take you directly to the page to make the approval.

To search for specific accounts or filter all accounts that are in a pending (for approval) state, navigate to Audience > Accounts > Listing. To show only the pending accounts, select Pending in the dropdown list State and click Search.

You can make individual approvals directly on each row, or select several rows at a time and perform a bulk approval.

To search for specific subscriptions to a service or filter all subscriptions that are in a pending (for approval) state, navigate to Audience > Accounts > Subscriptions.

To view Subscriptions, enable Service Plans in Audience > Accounts > Usage Rules.

You can select one subscription or several at a time and perform a bulk approval.

To search for applications or filter all applications that are in a pending (for approval) state:

You can select one application or several at a time and perform a bulk approval.

You can also start from the details page for a developer account, select which application you wish to approve from there, and make the approval on the application details page.

To search or filter specific accounts, navigate to Audience > Accounts > Listing.

You can select one or more rows at a time, and change the plans.

To search or filter specific subscriptions to a service, navigate to Audience > Accounts > Subscriptions.

You can only view subscriptions if you have enabled Service Plans in the Settings page.

You can select one or several subscriptions at a time, and change the plans.

To search or filter specific applications, navigate to Audience > Applications > Listing.

You can select one or several applications at a time, and change plans.

Another scenario is to start from the details page for a developer Account. From there you select the application for which you wish to change plan. On the application details page, you can change the plan.

When you navigate to [Your_product_name] > Applications > Settings > Usages Rules under Application Plan Changing in the Admin Portal, the option you select determines how users initiate changes. The following describes what happens depending on the option you select:

When a developer wants to change an application plan on the Developer Portal, for example, change to an Unlimited plan, the change is completed by email. The developer must login to the Developer Portal to complete the request to change their plan.

When an administrator receives an email requesting a change to an application’s plan, use the following steps to complete the process. It outlines how to select and confirm the new plan. Additionally, developers receive a notification of the change, allowing them to verify the update on the Developer Portal.

3scale API Management automatically sends an email notification to the developer informing them of the plan change, using the Application plan changed for buyer template. The developer can verify the plan change on the Developer Portal.

If you already know the account and developer who manages the application in question, navigate to their account from the Accounts page in Audience > Accounts > Listing, as shown below.

If you only have the application ID or API key, you can use the search box on the Accounts page in Audience > Accounts > Listing to find the relevant account. More information on locating applications is available here.

Once you are in the account profile page as shown below, click the message icon.

The message created here will be sent both to the account system dashboard, where all developers on the account will see it, and by email to the people on the developer account who have admin status within the account.

If it’s an emergency and email is unlikely to be fast enough for your purposes, you can also use the contact information submitted by the developer at time of signup, which is available:

Note that you can make contact phone numbers a required field upon signup.

To view the details page for the developer Account you are interested in:

Select the application whose plan you wish to customize.

Select the option to “customize”. This provides the page where all the plan elements can be customized for the application owned by this account.

To find an application, you need the name of the account it belongs to or the application’s name. If you do not have this information, you can verify the access logs. To perform the search, navigate to Applications: Audience > Applications > Listing.

If you search by identifier for an authentication type, you need the following information:

To search a given application, navigate to Applications page via Audience > Applications > Listing, and use the search box as shown in the image below.

Once the results are returned, click on the application you would like to access and you will be taken to that application’s homepage, which includes information such as that shown in the image below.

Unsubscribe a single developer from a service they are subscribed to through the Admin Portal:

Perform a bulk action to unsubscribe multiple developers from a deprecated or deleted service:

Remember that service plans need to be enabled.

You can find the application from the Accounts or Applications tabs or by searching as described here.

Once you have located the application and see the application summary page, click on the suspend icon next to the State value. This action will immediately disable the application from the API and suspend all keys from working. Calls with these application keys will be rejected by the control system.

The application can be unsuspended using the same button once the problematic behavior has been rectified.

How you contact the developer of the application will depend on your workflow and policy. On the same page, you can click on the account name, which will take you to the account view where you can identify the key administrator of the account that owns the application. You can contact them either by email or by clicking on the send message button as shown, which will generate a dashboard message for the user.

Adding a method to a product or backend means that you are designating a method in your API for which you want to capture individual usage details. An application plan provides the ability to set a limit for each method that you add to a product or backend. The procedure for adding a method or metric to a product is similar to adding a method or metric to a backend.

Adding a metric specifies a usage unit that you want to capture for all calls to your API. An application plan provides the ability to set a limit for each metric that you add to a product or backend. The procedure for adding a method or metric to a product is similar to adding a method or metric to a backend.

If your API has multiple endpoints, there are two ways to automatically designate methods and add metrics to 3scale products and backends:

Mapping rules are operations that are mapped to previously created methods and metrics in your products and backends.

By default, when your 3scale account is created, you are given two plans: Basic and Unlimited. You can keep and edit these, or create your own. You can create as many plans as you need.

To create a new application plan, follow these steps:

Once you have created a plan, you can provision rate limits and set up paid plans.

After you have created all your plans, you can select a default plan for when people sign up to register their applications.

To select a default application plan:

If you do not indicate a default application plan, when a new user signs up to get access to your API, they will not be created an application by default. In other words, the user will not be able to get access to your API.

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

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.

In the edit application view, you can enter or modify the upfront charges and subscriptions.

Next, set up the pricing drivers you selected in Section 21.1, “Deciding your pricing model”:

If some of them already exist as metrics, you can edit the item.

Once you are finished setting up your pricing rules, click Update Application plan.

You can 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, 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 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 common to differentiate between tiers using rate limits. This is explained in provision rate limits

If you do not have an application plan defined yet, create one first. Otherwise, select the plan you want to set rate limits for and click edit.

For more details about creating application plans, see Application plans.

To set the rate limits:

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

Once your rate limits are operational, you will see the users who are reaching the limits on your dashboard, making it quick and easy to check for potential plan upgrade candidates. For more information about soft and hard limits, refer to the Getting Started guide in Configure your API access policies with application plans for the Advanced path.

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

Billing in 3scale is based on the calendar month, and can be Prepaid and Postpaid.

For more details, see Automated billing process.

This setting enables credit card transactions. When this setting is on, all due invoices will be charged using the selected payment gateway. If you leave this setting off, billing will take place and invoices will be issued, but no real payment transaction will take place.

Select the currency in which billing and the credit card transactions will be made. Please make sure that the selected currency is supported by your payment gateway. This setting is global and applies to all invoices and transactions; it is not possible to set different currencies for different developer accounts.

The text introduced in the Invoice footnote field will appear at the bottom of every PDF invoice. You can use this field to provide additional information about the charging and billing policy for your customers.

If the text of the footnote is changed, it doesn’t automatically apply to the invoices, for which the PDF has already been generated. However, it is possible to apply the change by regenerating the PDF of the invoices.

The field is used to add a text message to the PDF invoice, in case VAT / Sales Tax is 0% for the billed account. This line will only appear if the VAT / Sales Tax is set to 0 explicitly, otherwise it will not be shown. Additionally, the text will also appear on the Invoice page in the Admin Portal.

See more about this setting in VAT / Sales Tax section

The currencies.yml file allows you to configure a list of currencies for your 3scale deployment. 3scale uses three-letter currency codes based on ISO 4217.

Invoices in 3scale have two types of identifiers:

This setting defines the format of the Friendly ID of the invoice:

The only effect of changing the billing periods for invoice identifiers from monthly to yearly is changing the friendly identifier format. This modification does not change the billing cycle period. Only monthly billing is supported by 3scale API Management. Changing the format of the invoice identifiers to yearly can be used, if there is such a requirement from your accounting department.

If you need to charge the customers yearly, billing should be handled manually - you can create a new invoice and add a line item with the yearly cost. If you prefer to use yearly charging, you may also want to set your application plans to be free, to make sure the invoices are not generated and/or charged automatically each month.

Here, you can configure the path to the following pages:

3scale integrates with the following payment gateways for credit card transactions:

Online payment services must display a mandate when collecting credit card data. A mandate is a record of the permission a customer has given you to debit their payment method. The mandate should state clearly that the supplied payment method will be used to collect subsequent payments for services. For more information regarding mandates for Stripe and Braintree, see the external documentation links for the respective payment gateways listed under Additional resources.

As a 3scale API provider, configure the Admin Portal and the Developer Portal with Stripe as a payment gateway to receive payments from subscriptions to your APIs by using Stripe as a credit card gateway.

As a 3scale API provider, configure the Admin Portal and the Developer Portal with Braintree as a payment gateway to receive payments from subscriptions to your APIs by using Braintree.

Back to Procedure.

Back to Procedure.

Back to Procedure.

As a 3scale API provider, allow the payment of rejected invoices via the Developer Portal. To enable these payments, update the Invoices template in the Admin Portal. Note that this procedure is intended for existing instances of the Developer Portal.

As a 3scale API provider working with either Stripe or Braintree as payment gateways, you can troubleshoot some issues with these credit card gateways.

Pricing rules define the cost of each API request. Multiple pricing rules on the same metric divide up the ranges of when a pricing rule applies. Pricing rules are based on calendar month, and the counter is reset at 00:00 UTC of the 1st day of each month.

Until 100 calls per month (from 1 to 100) each API call can be charged at $0.04, and starting from the call 101 (from 101 to infinity) the calls are charged at $0.10.

The first 1000 calls are not charged (cost $0), because they are included in the plan which has a monthly fixed cost. Starting from call 1001, each call is charged at $0.50.

Calls from 1 to 100 are charged at $0.30, 100 to 500 – at $0.40, and 500 and further – at $0.50.

Repeat the last two steps to create all the necessary pricing rules ranges.

Leave the To field empty to set the rule to to infinity.

The maximum number of decimals is set to 4 for the cost of metric, if a number is added with more decimals, the value is rounded to a number with 4 decimal places.

In the Audience > Billing > Earning by month section you can find an overview of your due and received payments, calculated as the sum of all invoices issued that month, depending on their state:

By clicking on a specific month you can list all invoices for that month.

You can also see the list of invoices by going to Audience > Billing > Invoices, where you can find invoices by their ID (friendly ID), the account name, and also filter by month and state.

The invoices of a specific developer account can also be found under X Invoices in the breadcrumbs of the account details page at Audience > Accounts > Listing > [selected account], where X is the number of invoices the account has.

If you click on the invoice friendly ID from the invoices list, you will see the details of the invoice.

The invoice can be in one of the following states:

In 3scale, the billing process runs daily. It generates invoices, changing their states according to the billing flow, and performs charges using the configured payment gateway.

The billing flow is a bit different for Prepaid and Postpaid mode, and as billing in 3scale is based on calendar month, there are special events that happen on the first day of the month.

Automated billing process generates invoices for all developer accounts subscribed to paid services.

Charging can be enabled or disabled globally. See Configuring Billing Settings, however it is also possible to enable or disable both billing and charging per developer account. To do that, navigate to the account page and click the corresponding button (Enable / Disable) against:

If charging is disabled, and billing is enabled, the developer will be issued invoices, but will not be charged. This is useful in case you handle charging separately, for example, with wire transfers.

If both are disabled, the developer will not be issued or charged.

If billing is disabled, and charging is enabled, the developer will not be issued any new invoices, but all the outstanding ones (Pending and Failed) will still be charged.

Here in the Billing Status block you can also see whether the credit card details are configured on the account. In case credit card details are configured, the month and the year of card expiration is shown. The presence of the credit card details may affect the Developer Portal flow on sign up and plan change (see more in Section 26.9, “Credit card flow”).

A trial period (in days) can be set for paid plans to delay the charging for the specified amount of days.

You can see the trial period status for the application in the application listing ([Your_product_name] > Applications > Listing) in the State column as live – trial expires in N days, and in the application details page in the Trial days left field.

During the trial period the application can use all the features and usage limits defined by the plan without restrictions.

Once the trial period is set, it is not possible to cancel or extend it. Upgrading to another plan will not reset the trial days counter.

10 days before the trial period expires, an email notification is sent to the developer account notifying about the upcoming trial expiration. The template of this email can be configured in Audience > Messages > Email Templates: Application trial period expired for buyer for the application plans, and Service trial period expired for buyer for service plans with trial period. The developer should either remain on the current plan, or switch to another plan, or contact the API provider if they decide to cancel the subscription.

Once the trial period is over, the next time automated billing runs (see Section 26.4, “Automated billing process”) the developer will be charged according to the costs set for the plan that the application or service are currently on. Note that the application will not be blocked or suspended after the trial period expires, and will continue to work.

While a trial period technically can be set for free plans, it is not recommended as the feature loses its usefulness.

Value-Added Tax (VAT) is a tax that is applied on goods and services sold within European Union. In other countries there is a similar tax, for example, Sales tax. API providers who charge their customers for using their API service often need to charge the tax as well and reflect it in the invoices to comply with the existing regulations.

3scale billing can automatically include VAT in the invoices, when configured.

_Total cost (without <VAT rate>)_ +
_<VAT rate> Amount_ +
_Total cost (<VAT rate> <VAT rate value>% included)_

The developers can manage their Credit Card information and see their invoices in the Developer Portal.

The Finance switch in Audience > Developer Portal > Feature Visibility has to be in Visible state for the developers to see the billing-related elements in the Developer Portal.

A logged-in user can update the credit card details at Settings > Credit Card Details. Depending on the payment gateway configured the form may be different, and the user may need to enter the billing address first.

A developer can only have one credit card card on the Developer Portal.

Credit card details cannot be deleted from the Developer Portal. The user of the developer account who wants to delete his credit card details would need to request the API provider to delete the credit card details from the system.

To see the invoices, the user can go to Settings > Invoices, and from there they can either show the details for each invoice, or download the invoice PDF.

When the developer enters the billing address on the Credit Card Details in the Developer Portal, this address is stored separately from the legal account address.

By default the legal address appears in the Invoices in the Issued to field. However, in case the developer does not have the legal address configured, but only the billing address, the latter will be used on the invoices. The organization name is considered part of the address in this case.

By default the billing address is not visible in the Admin Portal or through the product API; however you can add it as follows:

Now the <billing_address> field appears in the XML model for Accounts in the Account Management API and Webhooks. The corresponding billing address will be visible as read-only in the Account and the Account edit pages of the Admin Portal.

Billing address can be changed by the developer in the Developer Portal, in the Credit Card Details section. The admin cannot change the billing address in the Admin Portal, but it is possible to do so with the Account Edit endpoint of the Account Management API using the following fields as additional fields:

billing_address_name
billing_address_address1
billing_address_address2
billing_address_country
billing_address_city
billing_address_state
billing_address_zip
billing_address_phone

The users of the 3scale account (admins and members with Billing permission) can subscribe to or unsubscribe from the notifications related to billing at Account Settings (gear icon on the top-right) > Personal > Notification Preferences, under Billing section:

The email notifications sent to the developer accounts can be configured at Audience > Messages > Email Templates. The following emails are available:

All admin users of the developer account will receive the above notifications.

When Service Discovery is configured, 3scale scans for discoverable API services that are running in the same OpenShift cluster and automatically imports the associated API definitions into 3scale. Additionally, 3scale can update the API integration and its specification, based on OpenAPI Specification (OAS), to resynchronize them with the cluster.

Service Discovery offers the following features:

When you import a discoverable service, it keeps its namespace within the project it belongs to. The imported service becomes a new customer-facing API, product, and its corresponding internal API, backend.

If you want to have 3scale discover an API service in an OpenShift (OCP) cluster, said OCP service must meet the criteria for each element below:

As a 3scale administrator, you have two options to configure Service Discovery: with or without an Open Authorization (OAuth) server.

If you configure 3scale Service Discovery with an OAuth server, this is what happens when a user signs in to 3scale:

To configure Service Discovery with an OAuth server, you have the following options:

If you configure Service Discovery without an OAuth server, when a user signs in to 3scale, the user is not redirected. Instead, the 3scale Single Service Account provides a seamless authentication to the cluster for the Service Discovery. All 3scale tenant administration users have the same access level to the cluster while discovering API services through 3scale.

As a 3scale system administrator, allow users to individually authenticate and authorize 3scale to discover APIs by using OpenShift built-in OAuth server.

As a system administrator, allow users to individually authenticate and authorize 3scale to discover services by using Red Hat Single Sign-On for OpenShift.

For an example about configuring OpenShift to use the Red Hat single sign-on deployment as the authorization gateway for OpenShift, you can refer to this workflow.

To configure the 3scale Service Discovery without an OAuth server, you can use 3scale Single Service Account to authenticate to OpenShift API service.

From the OpenShift cluster, import a new API service that conforms to the OpenAPI Specification. This API is managed with 3scale.

As an OpenShift project administrator, you can authorize a 3scale user to access a namespace when the OAuth token is not valid.

You can update (refresh) an existing API service in 3scale with the current definitions for the service in the cluster.

A master administrator monitors and manages the 3scale accounts through the Master Admin Portal and API endpoints. Similar to the standard Admin Portal, the Master Admin Portal contains information about all the accounts of a deployment, and allows for administration of accounts and users through a unique account page.

For details on account administrator operations, refer to the Accounts guide.

30.1.1. Accessing the Master Admin Portal

To access the Master Admin Portal, you need to use the credentials and URL specifically defined for the Master Admin Portal during the on-premises installation process.

The Master Admin Portal URL consists of the MASTER_NAME (master by default in the template) and the WILDCARD_DOMAIN:

<MASTER_NAME>.<WILDCARD_DOMAIN>

You can identify the Master Admin Portal by the Master flag.

You can manage accounts through the Master Admin Portal or through API calls.

30.2.2. Managing accounts through API calls

You can manage accounts through the Master Admin API calls. For information on these calls, refer to the Master API section, by clicking the question mark (?) icon located in the upper-right corner of the Master Admin Portal, and then choosing 3scale API Docs.

As a result of multiple accounts existing under the same OpenShift cluster domain, individual account names prepend the OpenShift cluster domain name as subdomains. For example, the route for an account named user on a cluster with a domain of example.com appears as:

user.example.com

A standard multitenant deployment will include:

Additional accounts added by the master admin will be be assigned a subdomain based on their names.

Resuming a tenant account implies restoring an account scheduled for deletion. You can resume a tenant account up to 15 days after you have scheduled it for deletion.

After resuming an account:

3scale acts as an infinitely scalable data repository for your API product statistics. You can use metrics and methods to capture API product statistics so that you have the information necessary to optimally manage access to your API. For example:

You can track more metrics that are relevant to your API product. 3scale can track an arbitrary number of metrics and methods, as long as it is a countable quantity that can be incremented over time.

Once you have chosen the metrics you want to use, register them in the Admin Portal by using the procedure described in Adding metrics to products and backends.

You can add metrics and methods to the product or backend you have selected. Provide them with a friendly name and a system name, which 3scale uses in the plugin configuration. For more details about creating methods and metrics, see Designating methods and adding metrics for capturing usage details.

When 3scale is ready with the names of the metrics you want to track, you need to configure your plugin to report those metrics. The precise manner of doing this depends on the plugin or integration method in use. By default, the plugins report the Hits, API transactions, metric only.

For additional information about different endpoints, refer to the 3scale API Documentation, available in the Admin Portal under Account Settings > Integrate → 3scale API Docs.

You can view the traffic data for a given API configured as a backend. The Traffic page shows the hits to the endpoint.

Establish a connection between the API and 3scale so that you can send traffic to the API product and watch it register on the API Analytics dashboard.

Besides the usage graphs in the Analytics section, you can access analytics data with the Analytics API. The 3scale Analytics API is a flexible way to extract all analytics data for your API product in either XML or JSON format.

If traffic does not display on the usage charts in the [Your_product_name] > Analytics > Traffic, perform the following checks.

A customer was in the process of onboarding thousands of new developers per week. This customer could tackle some aspects of the onboarding because 3scale provides automated necessities such as key provisioning, sign-up workflows, and email communication. There was, however, something that was not possible to do with 3scale, which was quite important for them.

Since the customer was onboarding many people, the company needed a straight-forward way to classify the new developers based on their engagement with APIs so that their operations and marketing teams could interact with the new developers more effectively. At least at the required level of detail, such a feature was not yet available in the built-in analytics tools provided by 3scale. However, it was possible to extract data using the 3scale Account and Analytics API because all the data was available in the system.

First, they wanted to know how many developers signed up but never used their API.

Second, they wanted to split the developers that had used their API into two groups:

This information is available in 3scale built-in analytics. The problem is that there is no view to show it aggregated, which makes the whole experience quite cumbersome.

To extract application analytics, start by working with ActiveDocs. 3scale ActiveDocs is available in your Admin Portal, under Account Settings > Integrate > 3scale API Docs. 3scale has all of its APIs available as ActiveDocs so that you can try them from your browser. This allows you to find the request that best serves your needs, get the request (curl-like) and get a grasp of the response. The following figure provides an ActiveDocs example:

This is the ActiveDocs for the API request that fetches all applications for which the script will extract analytics.

ActiveDocs lets you quickly understand what the API is able to do. Then, it is a matter of finding which 3 or 4 requests are needed for the task you want to do and putting a script together.

The following procedure shows the steps that achieved the custom analytics that the example customer wanted.