API Bizops

Red Hat 3scale API Management 2.2

How to add / invite developers, account and application approvals, contacting developers, etc.

Red Hat Customer Content Services

Abstract

This guide documents business operations with Red Hat 3scale API Management 2.2.

Chapter 1. Adding Developers

These are the steps to add a new developer account for access to your API.

If you have configured the workflow to invite developers manually, this covers how to add new developers.

1.1. Step 1: Create the new developer account

On the Accounts page of your Admin Portal, create the new account. 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.

Create new developer account

1.2. Step 2: Set up applications

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.

Add applications to new account

1.3. Step 3: Notify the developer

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

Chapter 2. Approving Developers

This section shows how to make approvals for any step in the signup workflow.

Once you’ve implemented the signup workflow with manual approval steps, you have a few options. The approval process is slightly different depending on the trigger and what is being approved. If you receive an email notification, follow the instructions in the following section. Otherwise, it depends on whether you want to approve an account, a service, or an application.

2.1. Approve from email notification

If you (as 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.

2.2. Account approval

From the Accounts page of your Admin Portal, you can search for specific accounts or filter all accounts that are in a “pending” (for approval) state. You can make individual approvals directly on each row, or select several rows at a time and perform a bulk approval.

Developer approval account signup

2.3. Service approval

From the Service Subscriptions page, you can search for specific subscriptions to a service or filter all subscriptions that are in a “pending” (for approval) state. Then you can select one subscription or several at a time and perform a bulk approval.

Developer approval service subscription

2.4. Application approval

From the Applications page, you can search for applications or filter all applications that are in a “pending” (for approval) state. Then you can select one application or several at a time and perform a bulk approval.

Developer bulk approvals apps

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.

Developer individual app approval 1
Developer individual app approval 2

Chapter 3. Changing Plans For An App

After this section you will be able to change plans for accounts, services or applications

As admin you may change plans for a developer at any time, or in response to a plan change request that the developer initiates.

Note

The change plans step is slightly different depending on what type of plans are being changed.

3.1. Change Account Plans

From the Developers page, you can search or filter specific accounts. Then you can select one or more rows at a time, and change the plans.

developer change account plans

3.2. Change Service Plans

From the Service Subscriptions page, which you can only view if you have enabled service plans from the settings page, you can search or filter specific subscriptions to a service. Then you can select one or several subscriptions at a time, and change the plans.

Change service plan

3.3. Change Application Plans

From the Applications page, you can search or filter specific applications. Then you can select one or several applications at a time, and change plans.

Change plans for multiple applications

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.

Change application plan

3.3.1. More Information

If rather than change to another standard plan, you only want to make a change for one specific app, you can use the customize plans feature.

Chapter 4. Contacting Developers

This guide explains how to find out which developer account manages a particular application and then communicate with them – both through 3scale and externally.

During API operations, you may urgently need to contact developers who are using your API.

4.1. Step 1: Locate the relevant application and account in the system

If you already know the account and developer who manages the application in question, you can navigate to their account from the Accounts tab as shown below.

Accounts View

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

4.2. Step 2: Send an internal messages to developers

Once you’re on the account profile page as shown below, click on the message icon.

Send message

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.

4.3. Step 3: Contact by other means

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:

  • On the company account page (general contact information but may include a phone number)
  • Developer/user specific information on the users’ own file

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

Chapter 5. Customize Plans

When you have completed this section you will have customized an application plan for a specific developer.

Application plans are a good way to apply standard policies for different segments of your developer community. However, you always have the flexibility to customize the standard plans for any individual developer with unique requirements.

Once a plan is customized, you lose the link to the original plan. If you make changes to the original plan, the custom plan does not inherit any of those changes. So you should use this customization feature sparingly, before you become overwhelmed with too many custom plans which you cannot manage effectively.

A developer wants to increase their current limits without upgrading to the next pricing tier as the current billing period is already under way. A customization could be a good way to handle this situation by enabling the increase in limits and charging only the variable costs incurred. This would also help encourage an upgrade for the following billing month.

5.1. Step 1: Choose the account

First you should view the details page for the developer Account you are interested in.

Select Account

5.2. Step 2: Select the application

Select the application whose plan you wish to customize.

Select App

5.3. Customize the application plan

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

Customize Plans

5.3.1. More Information

Before you take the step to customize plans, always consider first if you are not better off with a new standard plan (which can be hidden from display in the Developer Portal). Then you would just change to the standard plan and so gain the benefit of reuse if this applies to more than one of your developer partners.

Chapter 6. Enable Signup

Configure developer signup by implementing self-service or manual mode.

You can configure the workflow for developers to be self-service or by manual invite only. Self-service signups are done by developers through the Developer Portal, while manual invites are handled by your admins through the Admin Portal.

All you have to do is change the checkbox toggle to signup enabled.

Enable self-service developer signup

Chapter 7. Finding Applications

By the end of this guide, you’ll be able to quickly locate an application in the Dashboard based on either its name, an API key, or an application identifier.

During API operations, you may need to be able to find information on an application that is accessing your API quickly – either for support purposes, to change configuration, or potentially because the application is misbehaving and needs to be disabled.

7.1. Step 1: Get the information you need

To find an application, you need to know something about it – the name of the account it belongs to or the application’s name. If you have this, locating it is straightforward from the Applications tab in the Dashboard. However you may have no information other than the application identifier or its API key, for example if you’re seeing this information in your own access logs.

If you’re searching by identifier then for the different authentication types, you need the following information:

  • For API key-only authentication patterns: the API key
  • For app ID and app key authentication patterns: the app identifier (search by app key is not supported)
  • For OAuth authentication patterns: the client_id (search on the secret is not supported)

7.2. Step 2: Search for the application

Armed with whatever data you have, head to the Applications area of the Dashboard, and use the search box (shown in the image below).

Findig an application part 1

7.3. Step 3: Access application information

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

Finding an application part 2

Chapter 8. Inviting Developers

After completing these steps, you will have added a new developer user to a developer account.

When you create a developer account manually, you can invite developer users to that account through the Admin Portal.

From Developers > Accounts page, select “invitations” and then “invite a user”.

Developer invite user

Chapter 9. Unsubscribing developers from a service

As an admin, you can unsubscribe developers from a service. You may need to do this for one specific developer, or for multiple developers, in the event of a service deprecation.

9.1. Unsubscribing a single developer from services

Unsubscribe a single developer from a service they are subscribed to through the admin portal:

  1. In the Admin Portal, navigate to: Developers > [select an account] > Service Subscriptions
  2. select Unsubscribe for the service that you want to remove the developer from

9.2. Unsubscribing multiple developers from services

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

Note

This method only applies to services that have been deleted or suspended. You cannot perform a bulk unsubscription action on active services.

  1. In the Admin Portal, navigate to: Developers > Subscriptions
  2. Using the service dropdown menu, identify the service from which you want to unsubscribe developers
  3. Using the checkboxes on the left, select the developers you want to unsubscribe
  4. Select Change State > Suspend to suspend the selected developer subscriptions

Chapter 10. Suspending Applications

This guide explains how to disable all keys and access tokens for an application.

If an application is misusing your API and affecting other traffic, you may need to quickly suspend its operations before contacting the developer involved to ask them to amend their code or configuration.

10.1. Step 1: Find the application

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

10.2. Step 2: Disable the application

Once you have located the application and see the application summary page, click the suspend icon below the name of the application. 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.

Suspend an Application
Note

If you use caching in your agents, suspension may not be immediate but require a short timeout.

10.3. Step 3: Contact the developer

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 under the submenu, 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.

Contact Developer

Chapter 11. Multitenancy

Red Hat 3scale allows multiple independent instances of 3scale tenants to exist on a single On-Premises deployment. A master administrator monitors and manages these tenants through a special master admin portal and API endpoints.

Tenants operate independently from each other, and cannot share information between themselves. They are administered by tenant administrators, who can perform the standard administrative actions under their tenancy. For details on tenant administrator operations, refer to the Accounts guide.

11.1. Master admin portal

The master administrator has access to the master admin portal. Similar to the standard admin portal, the master admin portal contains information about all tenants in a deployment and allows for administration of tenants and users through a unique tenant page.

11.2. Accessing the master admin portal

Access the master admin portal using the master admin portal credentials and URL defined and output during the on-premises installation process.

The master admin portal URL consists of the MASTER_NAME prepended to the -admin string subdomain:

<MASTER_NAME>-admin.<OCP_DOMAIN>

The master admin portal can be identified by the Master flag in the upper left corner.

Master tenant flag

11.3. Adding a tenant through the master admin portal

  1. Log in to your master admin account
  2. Select TenantsCreate

    Tenants Page
  3. Enter the required information:

    1. Username
    2. Email
    3. Password
    4. Organization/Group name

      Create Tenant
  4. Select the Create button to create the user

Once you select Create, Red Hat 3scale creates a tenant subdomain for your tenant based on the Organization/Group name.

11.4. Managing tenant accounts through the master admin portal

  1. Log in to the master admin portal
  2. Navigate to the Tenants page

    Tenants page
  3. Select the group or organization you wish to manage

From the Tenants page, you can perform administrative actions, such as impersonating a tenant admin or suspending a tenant account. You can also manage the following tenant account attributes:

  • applications
  • users
  • invitations
  • group memberships
  • organization/group name
Master tenant overview

11.5. Managing tenant accounts through API calls

You can manage tenant accounts though master admin API calls. For information on master admin API calls, Refer to the Master API section of the 3scale API Docs, available in the upper left corner of the master admin portal.

Master API section

11.6. Understanding multitenancy subdomains

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

user.example.com

A standard multitenant deployment will include:

  • A master admin user
  • A master admin portal route, defined by the MASTER_NAME parameter:

    <MASTER_NAME>-admin.<OCP_DOMAIN>
  • A tenant admin user
  • A tenant admin portal route, defined by the TENANT_NAME parameter:

    <TENANT_NAME>-admin.<OCP_DOMAIN>
  • A tenant AMP route:

    <TENANT_NAME>.<OCP_DOMAIN>
  • Tenant routes for the production and staging built-in APIcast gateway:

    <TENANT_NAME>-<!!! Not sure>-apicast-staging.<OCP_DOMAIN>
    <TENANT_NAME>-<!!! Not sure>-apicast-production.<OCP_DOMAIN>
    This example illustrates the output users and routes of a standard multitenant deployment of 3scale:
    ----
    --> Deploying template "3scale-project/3scale-api-management" for "amp.yml" to project project
    3scale API Management
    ---------
    3scale API Management main system
         Login on https://user-admin.3scale-project.example.com as admin/xXxXyz123
         ...
         * With parameters:
          * ADMIN_PASSWORD=xXxXyz123 # generated
          * ADMIN_USERNAME=admin
          * TENANT_NAME=user
          ...
          * MASTER_NAME=master
          * MASTER_USER=master
          * MASTER_PASSWORD=xXxXyz123 # generated
          ...
    --> Success
        Access your application via route 'user-admin.3scale-project.example.com'
        Access your application via route 'master-admin.3scale-project.example.com'
        Access your application via route 'backend-user.3scale-project.example.com'
        Access your application via route 'user.3scale-project.example.com'
        Access your application via route 'api-user-apicast-staging.3scale-project.example.com'
        Access your application via route 'api-user-apicast-production.3scale-project.example.com'
        Access your application via route 'apicast-wildcard.3scale-project.example.com'
        ...
    ----

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

Chapter 12. Webhooks

By the end of this section, you’ll be able to configure and take action on the webhooks for your Developer Portal.

The use of webhooks allows you to tightly integrate 3scale with your back-office workflow. When specified events happen within the 3scale system, your applications will be notified with a webhook message, and you can use the data such as from a new account signup to populate your CRM system.

12.1. Introducing webhooks

A webhook is a custom HTTP callback triggered by an event. In the 3scale system, all the possible events are displayed as in the screenshot below.

Howtos Webhooks Overview

When one of these events occurs, the 3scale system makes an HTTP (or HTTPS) request to the URI configured in the webhooks section. On your end, you can configure the listener to invoke some desired behavior such as event tracking.

The remaining two checkboxes on the screenshot turn on webhooks ("Webhooks are" switch) and allow webhooks to be fired by actions in the Admin Portal. The default behavior is to trigger webhooks only by actions triggered from within the Developer Portal. Bear in mind that this means not all events can be triggered.

12.2. Webhooks format

he format of the webhook is always the same. It makes a post to the endpoint with an XML document of the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<event>
  <type>application</type>
  <action>updated</action>
  <object>
    THE APPLICATION OBJECT AS WOULD BE RETURNED BY A GET ON THE ACCOUNT MANAGEMENT
    API
  </object>
</event>

The <type> gives you the subject of the event such as "application", "account", etc. The <action> – what has been done such as "updated", "created", "deleted". Finally the <object> is the XML object itself in the same format that is returned by the Account Management API. To check this, you can use our interactive ActiveDocs, available in your Admin Portal, under the Documentation → 3scale API Docs section.

If you need to provide assurance that the webhook was fired by 3scale, expose an HTTPS webhook URL and add a custom parameter to your webhook declaration in 3scale. For example: https://your-webhook-endpoint?someSecretParameterName=someSecretParameterValue. Decide on the parameter name and value. Then, inside your webhook endpoint, check for the presence of this parameter value.

12.3. Troubleshooting

If you want to experiment with the webhooks or troubleshoot issues, you may find RequestBin a great (and free) service to view the results of the webhooks: http://requestb.in/

If you experience an outage for your listening endpoint, you can recover failed deliveries. 3scale will consider a webhook delivered if your endpoint responds with a 200 code. Otherwise, it will retry 5 times with a 60 seconds gap. After any recovery from an outage, or periodically, you should run a check and if applicable clean up the queue. You can find more in the ActiveDocs for the two methods:

  • Webhooks list failed deliveries
  • Webhooks delete failed deliveries

Legal Notice

Copyright © 2019 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.