For external management systems getting access to the platform through the APS bus, the platform supports authentication and authorization via the OAuth Core 1.0 Revision A (hereafter OAuth-1.0a) protocol.

Set Up HTTPS Access to the Platform

The OAuth authentication protocol requires access to the platform only through a UI brand access point with the activated APS booster using the HTTPS protocol.

Production System

If your platform is in production, it must already have a UI node or UI cluster with the APS booster available through HTTPS. If it does not, follow the platform deployment guide to setup the UI cluster with the APS booster.

To verify if REST requests go through the APS booster, check HTTP headers in a response message. One of them must be X-APSBooster-Response:true.

Lab System

In your lab system, if you do not want to configure a separate UI node for simplicity, then you should configure a UI with a brand access point directly on the management node.

  1. In the provider control panel, navigate to Infrastructure > Service Nodes, and make sure the management node (for example, is in the Ready to provide state.

  2. Navigate to System > Settings and click Brands on the screen.

  3. Click Add New Brand and in the Domain field enter the domain name of the management node, that is, the same domain name you see in the browser address string. for example, “”.

  4. Click Next and on the next screen, click Finish.

After the above configuration, get access to the platform through the HTTPS protocol, for example:

Set Up the User’s Credentials

The OAuth-1.0a protocol requires a sender to have a trusted consumer key and secret pair. You can generate that pair for a user whose credentials an external system will use to manage resources on the platform.

  1. In the provider control panel, create a special staff member whose OAuth credentials the external management system will use.

  2. For the new staff member, generate the OAuth credentials:

    • In the provider control panel, open the details of the newly created staff member.

    • On the APS Bus Access tab, click Create to generate the Consumer Key and Consumer Secret.


      Save the consumer secret immediately, as it is visible only once. After you leave the screen, the consumer secret will not be visible anymore.

  3. In the Allowed Operations section, add a separate entry for a group of allowed custom operations exposed by a certain APS type. Each entry consists of two parts:

    • The ID of the APS type that exposes the allowed operations.

    • An HTTP method (the verb in operation declaration): either GET, POST, PUT, or DELETE.

    In the following example, the user is enabled to operate orders through the order manager by means of GET and POST requests:



    1. This restriction concerns only Custom Operations and does not do anything with the CRUD.

    2. When adding an allowed operation, omit the APS type version in the APS Type field.

    3. To configure APS Bus Access, a staff member must be granted the “OAuth APS Bus Access”=”Manage” privilege.

Choose a REST Client


To use OAuth-1.0a supported by the platform, choose a REST client that meets the following requirements.

  • The client must be able to construct the Authorization header compliant with the OAuth-1a protocol.

    This means the client must accept the two parameters that the platform generates - consumer key and consumer secret - and then construct the other required OAuth parameters in the header as in the following example:

    Authorization: OAuth
  • The client must be able to send REST requests through the HTTPS protocol and accept self-signed SSL certificates when testing some operations on a test platform.

  • The client must not encode special symbols used in Resource Query Language (RQL). For example, some REST clients replace parenthesis ‘(‘ and ‘)’ respectively for ‘%28’ and ‘%29’, which is not compatible with the RQL parser.

Sample Scripts

If your management system uses some scripts or binary executables based on a programming language, the best way is to find a library or modules that support the OAuth-1.0a protocol in that language.

For example, in a Python script, use the requests_oauthlib module that you can install through the Python package manager using:

$ sudo pip install requests_oauthlib

GET Request

A simple Python script that gets all available APS resources may look as follows:

#!/usr/bin/env python

from requests_oauthlib import OAuth1Session

# Enter input parameters:
consumer_key = 'ug7nnV3aq4VwGQQzyiFRDSGwa7QZY0YE'
consumer_secret = 'cccMHKhIIVupWAEWtYeQmg9DVe0DSP...'   # Cut for brevity
url = ''

# Set session parameters and get response:
session = OAuth1Session(consumer_key, consumer_secret)
response = session.get(url, verify=False)
print response.text

POST Request

Similarly, the following script sends a POST request on placing a sales order to subscribe an account to a service plan:

#!/usr/bin/env python

from requests_oauthlib import OAuth1Session

consumer_key = 'qcrtTudBOCeRTh0rhQSEuSMucj7uNxSy'
consumer_secret = '6X9Zspqd81NoJJ0EGMHvm2kWRqy...'  # Cut for brevity

url = ''

session = OAuth1Session(client_key=consumer_key, client_secret=consumer_secret)

order = {
    "type": "SALES",
    "accountId": "992d543f-e5e7-4439-a139-38b364ce49af",
    "products": [
            "planId": "6a8513fd-c222-42f0-ab47-985477e807c6",
            "period": {
                "unit": "MONTHS",
                "duration": 1
            "resources": [
                    "resourceId": "29086bff-284d-4d6b-ad59-404bbbda2152",
                    "amount": 10
                    "resourceId": "cb2ffba9-4f25-411c-b49d-418f2ec36f4b",
                    "amount": 3

response =, json=order, verify=False)


This is a quick demo illustrating generic and custom REST operations on the platform:

Sample GUI Client

You can also find a GUI tool that meets the above requirements. A GUI client helps you test selected key operations before implementing them in a management system. For example, the Insomnia REST client meets all the above requirements; it is used in the following example.

The preferences and request settings of Insomnia allow you to disable validation of SSL certificates and disable URL encoding.

../../_images/insomnia-preferences.png ../../_images/insomnia-settings.png

The OAuth 1.0 configuration section allows you to select the HMAC-SHA1 signature method, enter a consumer key, consumer secret, and the OAuth protocol version to construct all other fields for the Authorization header.


SSL Hints

When using HTTPS in your browser and REST client, you may meet the following cases when your action is rejected:

  • The REST client does not accept a self-signed certificate from your test platform.

    • If you use a REST client as a plugin in your browser, first get access to the platform from your browser using HTTPS and accept the SSL certificate. Then switch back to your REST client. Now it will accept the SSL certificate.

    • If your REST client is a separate application, turn off the SSL certificate verification in the application settings.

  • If you have reinstalled your test platform under the same domain name and you cannot log in to the platform control panel through your browser or REST client, the most probable cause is the cookies stored in the browser or the REST client from the previous installation making messages similar to “Your session has expired…” pop up regularly. Clear the old cookies received from the server and try again.

Using an External API Gateway


The platform allows the provider to have multiple resellers of various levels that need to access REST API to implement various integration scenarios such as CRM or Billing integration. To allow those systems to get access to the platform, the provider should consider the following ways:


The second way is recommended, as a specialized API gateway usually provides numerous features to improve the quality of API services, for example, by rejecting improper requests and using API analytics tools.

The provider uses the following platform features to control access through an API gateway:

  • The system property APS OAuth API Gateway URL specifies an API gateway integrated with the platform. The property is configured for every reseller separately in the reseller control panel (RCP).

  • The security privilege OAuth APS Bus Access assigned through a security role to a user allows the latter to manage or only view the APS Bus Access user configuration.

  • An access to the APS bus through the API gateway is allowed on behalf of a user authenticated through the OAuth protocol, as explained in the Set Up the User’s Credentials section.

Sample Scenario

The following is a typical scenario of setting and using an API gateway for a reseller.

  1. The provider subscribes to a third-party API gateway service and configures the acquired gateway to forward APS REST requests to the platform.


    The provider must ensure that the API gateway forwards its domain name in the X-Forwarded-Host header. It must be the host name specified by the client in the Host header.

    In the simplest configuration, the API gateway forwards all REST requests containing the /aps/2/resources/ prefix in the URL.

  2. The provider configures other API gateway specific services, for example, security restrictions and API analytics.

  3. The provider logs to the RCP on behalf of the reseller who requires an API gateway, then navigates to System > Settings and in the Systems Properties enters the API gateway URL in the APS OAuth API Gateway URL property.

  4. As explained in the Set Up the User’s Credentials section, the provider or an authorized reseller staff member creates and configures a user with a generated Key and Secret pair and a list of REST operations allowed on the APS bus for that user. The reseller’s external systems will use those credentials to send REST requests.

  5. A reseller’s external system can send the allowed REST calls through the API gate using the pair of OAuth Key/Secret for authentication and authorization. For example:

    GET https://api.gate-provider.test:10443/aps/2/resources
  6. The platform security system accepts an incoming request if its OAuth signature in the Authorization header is based on the correct gateway URL as configured by the respective APS OAuth API Gateway URL property.


If an API gateway URL is configured for a reseller, the platform does not accept APS requests coming in any way other than through that gateway from any system authenticated as a user of that reseller.

Recursively, a reseller can downstream the APS OAuth API Gateway URL property to sub-resellers. A reseller’s staff member can configure it themselves in their own reseller account if they are granted the “System Configuration”=”Manage” privilege.