Public API

13 min

Purpose

In order to allow 3rd party applications and custom projects, that are not hosted within hypercharge aws account, to interact with cms api, we need to implement access control on a application level. Current implementation is based on features provided by AWS API GateWay out the box, such as:

usage plans

api keys

intermediate authorization functions

Usage plans - provides a set of rules that can be applied for particular api key. The rules include next features:

limit access by number of requests per month

limit access by number of requests per second

limit access by number of concurrent requests

Api key acts the role of access token and can be used to grant access to particular api. Api key can be linked with one usage plan, and client, which is connected using api key, will be restricted by rules, provided by linked usage plan. In addition AWS provides functionality to interact with api keys and usage plans via HTTP REST interface. So we are able to interact with usage plans and api keys from inside of our core application.

Implementation

Current implementation is supposed to have global configuration dashboard to have opportunity to setup api keys and usage plans for particular tenants. Usage plans are predefined. Api keys can be created as many as it required. Api key can be applied to particular tenant and 3rd party application working with this tenant will be limited by rules of usage plan attached to the tenant api key.

There are additional objects needs to be setup for every tenant:

INTEGRATION group- needs to be defined via migration scripts during the tenant bootstrapping

INTEGRATION user - user that is defined as authorization principal during to handling the proper api key

Adding additional group and user provide opportunity to flexible setup of allowed actions that 3rd party application can do.

Current authentication/authorization flow:

API gateway handles request from client application and looking for api key in request headers

If key is present - api gateway validate this key and checks usage plan to make a decision if the request can be processed forward or has to be declined.

When request was confirmed on api gateway level, authorization lambda function intercepts this request and performs authorization procedure. It check if required tenant has provided api key, if so, authorization function initialize authorization context (principal) with group INTEGRATION and user INTEGRATION. In other cases authorization function declines request.

In case when authorization function fully handle request, it proxies this request to target lambda function, responsible for particular api call.

Tenant configuration:

There are required to setup some data objects:

Attached to tenant api key

Create INTEGRATION group

Create INTEGRATION user which belongs to INTEGRATION group.

As we do not have global dashboard to setup a tenant configuration, we need to attach api key manualy in database:

connect to database which keeps data for required tenanat

go to tenants table

extend object, located in data field with additional property:

{
    ...
    apiKey:<id of api key that fits current tenant>,
    ...
}

Required users and groups should be bootstrapped automatically for new tenant during the tenant bootstrapping process. For existing tenants all data should be added manually in database directly.

API Keys and Usage Plans interactions

API endpoints to interact with existing usage plans and api keys are protected with generic authorization middleware function that is used to protect all hyperportal apis, To be able to interact with usage plans and api keys it is required to have access token.

API Definitions

Authorization

Authenticate by email

URL: https://{{tenant-id}}.hyper1.net/v2-auth/email/request METHOD: POST PATH PARAMETERS: - tenant-id - required tenant id to log in PAYLOAD:

{
    "tenantId": "xpowernv",
    "email": "[email protected]"
}

When you call this api endpoint with proper tenant id and email, you have to receive authorization code on your email. This authorization code has to be used to proceed forward with authorization process.

Authorize by authorization code and get access token

URL: https://xpowernv.hyper1.net/v2-auth/email/login METHOD: POST PATH PARAMETERS: - tenant-id - required tenant id to log in PAYLOAD:

{
    "tenantId": "xpowernv",
    "entityId": "EcPsggqRfcRJDMRYPBkJN",
    "email":"[email protected]",
    "code":"697189"
}

(NOTE: "entityId" = the entityId of the user, in case of this example, the entityId of user "[email protected]") RESPONSE:

{
    "idToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Im05MXk3M2ZqMzcifQ.eyJ0ZW5hbnRJZCI6Inhwb3dlcm52Iiwic3ViIjoiRWNQc2dncVJmY1JKRE1SWVBCa0pOIiwiZW50aXR5RG9tYWluIjpudWxsLCJncm91cHMiOlsib3duZXJJc19fRWNQc2dncVJmY1JKRE1SWVBCa0pOIiwiaHlwZXJBZG1pbnMiLCJoeXBlclVzZXJzIl0sInRlbmFudFBlcm1pc3Npb25zIjpbIkFQUF9BRE1JTiIsIlBPUlRBTCIsIkNNUyIsIldPUktGTE9XUyIsIk1BSUxfVEVNUExBVEVTIl0sInRlbmFudERlZmF1bHRMYW5ndWFnZSI6ImVuIiwiYXVkIjpbIkhZUEVSIiwiZWNvbW0iXSwiaWF0IjoxNTk3MzExMjIxLCJleHAiOjE1OTczMTMwMjF9.fYz0qgOpbDqCLmdArrdL6-tfPC8KKV35lHPXwS7yhFxoAtNAvhumlcmY1nh4x8-O6eE5BpjK_jIgBa-YWggoo1eCIsBbegST5JvoZSkv-FjvH0jT891Gb5k1ISdaiDWV71t00fblsV7sfFqLgfKU47qnOVwCBoceYj27ubVCWFcZmgpvnHA0eKwVgFNAMusFakqfMYO9sAP3lpAWUsS73SGQTCLBqvbqWoqn94jhaKUh9QNEWV6eqYevisAKiWhlX-0ZiRi_OXwaUkSubDRpxBeN2tUaM995ZZwrknuFgYDPFvWU66gJD6cZjAIQzlXYkXCra4lPgBbrsIe-7nrPZQ",
    "refreshToken": "pTvbBcKKtZKBNZJYXyYiPujUDbQLGEzEOlfMg0Gu89M=",
    "refreshTokenExpiry": 1599903221017
}

You need to use idToken for request authorization purposes.

Usage plans

All api request has to have header:

Authorization: Bearer <id-token>

Get all available api keys

URL: https://{{tenant-id}}.hyper1.net/v2-integrations/api-keys METHOD: GET PATH PARAMETERS: - tenant-id - required tenant id to log in RESPONSE:

[
    {
        "id": "39afcg4029",
        "name": "X-Power API Key",
        "description": "test integration api key",
        "enabled": true,
        "createdDate": "2020-07-12T19:24:49.000Z",
        "lastUpdatedDate": "2020-07-12T19:24:49.000Z",
        "stageKeys": []
    }
]

Get all available api keys that can be assigned to any of usage plans

Create a new api key

URL: https://{{tenant-id}}.hyper1.net/v2-integrations/api-keys METHOD: GET PATH PARAMETERS: - tenant-id - required tenant id to log in PAYLOAD:

{
    "name": "Very first api key",
    "description": "description of very first api key"
}

RESPONSE:

{
    "id": "yr1af8ey7d",
    "value": "B5w0vS7ofn78muHCiFdRG3shbX34OMKZ1EMzNDPh",
    "name": "Very first api key",
    "description": "description of very first api key",
    "enabled": true,
    "createdDate": "2020-08-13T10:23:02.000Z",
    "lastUpdatedDate": "2020-08-13T10:23:02.000Z",
    "stageKeys": []
}

Delete existing api key

URL: https://{{tenant-id}}.hyper1.net/v2-integrations/api-keys/{{api-key-id}} METHOD: DELETE PATH PARAMETERS: - tenant-id - required tenant id to log in - api-key-id - id of the existing api key you are going to delete

Get all available usage plans:

URL: https://{{tenant-id}}.hyper1.net/v2-integrations/usage-plans METHOD: GET PATH PARAMETERS: - tenant-id - required tenant id to log in RESPONSE:

[
    {
        "id": "2lj0ix",
        "name": "Plan_unlimited",
        "description": "Customer's unlimited usage plan",
        "throttle": null,
        "quota": null
    },
    {
        "id": "b1a6ak",
        "name": "Plan_basic",
        "description": "Customer's basic usage plan",
        "throttle": {
            "burstLimit": 200,
            "rateLimit": 100
        },
        "quota": {
            "limit": 5000,
            "offset": null,
            "period": "MONTH"
        }
    },
    {
        "id": "i3fawu",
        "name": "Plan_extended",
        "description": "Customer's extended usage plan",
        "throttle": null,
        "quota": {
            "limit": 10000,
            "offset": null,
            "period": "MONTH"
        }
    }
]

Get assigned keys in scope of particular usage plan

URL: https://{{tenant-id}}.hyper1.net/v2-integrations/usage-plans/{{usage-plan-id}}/api-keys METHOD: GET PATH PARAMETERS: - tenant-id - required tenant id to log in - usage-plan-id - the scope to retrieve list of the keys RESPONSE:

[
    {
        "id": "39afcg4029",
        "type": "API_KEY",
        "name": "X-Power API Key"
    }
]

Assign key to particular usage plan

URL: https://{{tenant-id}}.hyper1.net/v2-integrations/usage-plans/{{usage-plan-id}}/api-keys METHOD: POST PATH PARAMETERS: - tenant-id - required tenant id to log in - usage-plan-id - the scope to assign the key PAYLOAD:

{
    "apiKeyId": "39afcg4029"
}

Here might be an error it this key is already assigned to current usage plan

Remove api key from usage plan

URL: https://{{tenant-id}}.hyper1.net/v2-integrations/usage-plans/{{usage-plan-id}}/api-keys/{{api-key-id}} METHOD: DELETE PATH PARAMETERS: - tenant-id - required tenant id to log in - usage-plan-id - the scope to assign the key - api-key-id - api key that is required to remove from usage plan

CMS Bridge

https://hypercharge.hyperportal.org/swagger/

Postman collections:

for postman collection please contact developers