Amplify Central Connected Gateway Custom API Subscription Flow – Introduction

This blog post is the first in a series covering custom API subscription approval flows for Amplify Central Connected API Gateways using agents. You can read about it in more detail here.

In this document, we will start with the basics and describe how an API consumer subscribes to an API and how an API approver manually approves or rejects the subscription request through the Amplify Central user interface here. In future documents, we will look at integrating with custom subscription approval flows.

Overview

API subscriptions are used to secure access to an API in the Amplify Unified Catalog. When enabled, API consumers must subscribe to an API before getting access to it. Once approved, an email is sent to the API Consumer with the credentials for accessing the secure API.

As an asset provider, you can choose to disable subscriptions for your asset, for instance, if you want to publish an API that is not secured with an API Key. In this case, consumers can use the API without having to subscribe.

Here are the steps involved in requesting and manually approving an API subscription request:

• API Consumer discovers an API in the Unified catalog
• API Consumer subscribes to the API in order to request security credentials (e.g., an API Key)
• API Approver sets the subscription to approved or rejected
• API Consumer gets subscription details (e.g., credentials) via an email or by other means
• If approved, API Consumer can access the API

API Consumer discovers an API in the Unified Catalog

• API Consumer logs into the Unified Catalog and reviews available APIs:

• API consumer discovers an API that they would like to try (e.g., Stockquote). This API requires a subscription in order to obtain API credentials (e.g. API Key):

API Consumer subscribes to the API

• API consumer clicks on the Subscribe button and enters a name for the subscription, as well as selects a Team and App for the subscription:

• API is now in waiting for approval state:

API Approver Responds to Subscription Request

• API approver reviews subscription request

The following screenshots illustrate the steps the API Approver takes to manually approve the subscription request:

API Consumer Gets Access to the API

• API consumer receives an email with security credentials:

Note that emailing the credentials is only one option. Amplify supports other means, as well but these are beyond the scope of an introduction.

• API consumer accesses API:

The following screenshots illustrate the steps the API Consumer takes to test the API:

How to Enable Manual Subscriptions and Email Notification

In order to enable manual subscription approval and email notification, you need the following prerequisites:

• Connected Gateway using agents (Axway APIM or AWS)
• The Discovery Agent should be configured for the following:
  • Manual subscription approval
  • Email notification

This can be accomplished by editing the discovery agent YML file (fragment shown below):

.
.
.
subscriptions:
  approval:
    mode: manual

  notifications:
    smtp:
      host: email-smtp.us-east-1.amazonaws.com
      port: 587
      username: xxxxxxxxxxxxxx
      password: yyyyyyyyyyyyyy
      authtype: PLAIN
      fromAddress: noreply-demo@axway.com
      subscribe:
        subject: Subscription Notification
        body: |
           Subscription created for Catalog Item:  <a href= ${catalogItemUrl}> ${catalogItemName} </a> <br/>
           ${authtemplate}<br/>
        oauth: Your API is secured using OAuth token. You can obtain your token using grant_type=client_credentials with the following client_id=<b>${clientID}</b> and client_secret=<b>${clientSecret}</b>
        apikeys: Your API is secured using an APIKey credential:header:<b>${keyHeaderName}</b>/value:<b>${key}</b>
      unsubscribe:
        subject: Subscription Removal Notification
        body: |
           Subscription for Catalog Item: <a href= ${catalogItemUrl}> ${catalogItemName} </a> has been unsubscribed
      subscribeFailed:
        subject: Subscription Failed Notification
        body: |
             Could not subscribe to Catalog Item: <a href= ${catalogItemUrl}> ${catalogItemName} </a>
      unsubscribeFailed:
        subject: Subscription Removal Failed Notification
        body: |
           Could not unsubscribe to Catalog Item: <a href= ${catalogItemUrl}> ${catalogItemName} </a>

.
.
.

Alternatively, this can be accomplished by editing the discovery agent environment file (fragment shown below):

.
.
.
CENTRAL_SUBSCRIPTIONS_APPROVAL_MODE=manual
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_HOST=email-smtp.us-east-1.amazonaws.com
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_PORT=587
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_USERNAME=xxxxxxx
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_PASSWORD=yyyyyyyy
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_AUTHTYPE=PLAIN
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_FROMADDRESS=noreply-demo@axway.com
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBE_SUBJECT=Subscription Notification
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBE_BODY=Subscription created for Catalog Item: <a href= ${catalogItemUrl}> ${catalogItemName} </a> <br/>Your API is secured using an APIKey credential: header:<b>${keyHeaderName}</b> / value:<b>${key}</b><br/>${authtemplate}<br/>
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBE_OAUTH=Your API is secured using OAuth token. You can obtain your token using grant_type=client_credentials with the following client_id=<b>${clientID}</b> and client_secret=<b>${clientSecret}</b>
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBE_APIKEYS=Your API is secured using an APIKey credential:header:<b>${keyHeaderName}</b>/value:<b>${key}</b>
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_UNSUBSCRIBE_SUBJECT=Subscription Removal Notification
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_UNSUBSCRIBE_BODY=Subscription for Catalog Item: <a href= ${catalogItemUrl}> ${catalogItemName} </a> has been unsubscribed
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBEFAILED_SUBJECT=Subscription Failed Notification
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBEFAILED_BODY=Could not subscribe to Catalog Item: <a href= ${catalogItemUrl}> ${catalogItemName} </a>
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_UNSUBSCRIBEFAILED_SUBJECT=Subscription Removal Failed Notification
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_UNSUBSCRIBEFAILED_BODY=Could not unsubscribe to Catalog Item: <a href= ${catalogItemUrl}> ${catalogItemName} </a>
.
.
.

Summary

In this blog post, we described what an API subscription request and manual approval look like in Axway’s Amplify Central and the Unified Catalog. In subsequent posts, we’ll look at how we can integrate Amplify Central and the Unified Catalog with your own custom API subscription flow.