Feature - Manage subscription workflow

A subscription provides the consumer, or subscriber, with the required security and endpoint materials to correctly consume the API. The security material and/or quota to access an API is configured inside the application on Axway API Manager.

9 minute read

Supported use cases when consumer subscribes to an API

  • API providers allow the subscriber to create an application (property APIMANAGER_ALLOWAPPLICATIONAUTOCREATION=true set in the discovery agent configuration file): the agent generates the application and adds the access to the API from the newly created application.
  • Application has no access to the API in Axway API Manager: the agent adds access to the API from the selected application.
  • Application already has access to the API in Axway API Manager: the agent has nothing to do.

Supported use cases for issuing consumer credentials

The property APIMANAGER_SUBSCRIPTIONSISSUENEWCREDENTIALS allows the API provider to issue new credentials each time a consumer subscribes to an API (default behavior) or reuse existing credentials.

  • generate new credentials (default): new credentials (ApiKey / oauth client&secret ) are generated per subscription and store within the selected application.
  • reuse existing credentials (property APIMANAGER_SUBSCRIPTIONSISSUENEWCREDENTIALS=false set in the Discovery Agent configuration file): the agent sends the first non-repudiated credentials available in the application to the subscriber.

Supported use cases for subscription approval

Each API can define its own approval mode:

  • manual (default): an API provider has to approve the subscription before the consumer receives the API credentials. (Optional) the agent configuration contains a webhook information that will be triggered on each subscription state change. The webhook implementation can, for instance, trigger an MS Teams card to a dedicated Teams channel where the API provider will approve the subscription.
  • automatic: the subscription is auto-approve without human intervention.

Supported use cases for receiving API credentials

Once the subscription is approved, the agent catches this event from AMPLIFY Central and, based on its configuration, can forward the credentials using either an SMTP server or a webhook.

  • email: the agent configuration contains the access details to an SMTP server (endpoint / port / credentials, if any) and the templates for the emails. Emails can be triggered when the subscription succeeds, fails or when unsubscribes to an API. The agent configuration allows you to customize the email template with several properties:

    • ${catalogItemUrl}: url of the catalog item to help consumer find it easily
    • ${catalogItemName}: name of the catalog item
    • ${keyHeaderName} / ${key}: apiKey header name and apiKey value
    • ${clientID} / ${clientSecret}: oauth clientID and clientSecret to request the oauth token
    • ${message}: error message raised by the agent when the subscription fails or the unsubscribe fails

For more information about this configuration, see Customizing SMTP notifications.

  • webhook: the agent configuration contains the webhook details about where to send the payload (catalog asset url / catalog asset name / subscriber email / credentials / action=APPROVE / authtemplate=preconfigure security template sentence).

Webhook payload definition:

{
    "type": "object",
    "properties": {
        "catalogItemId": {
            "type": "string"
        },
        "catalogItemUrl": {
            "type": "string"
        },
        "catalogItemName": {
            "type": "string"
        },
        "action": {
            "type": "string"
        },
        "email": {
            "type": "string"
        },
        "key": {
            "type": "string"
        },
        "keyHeaderName": {
            "type": "string"
        },
        "authtemplate": {
            "type": "string"
        }
    }
}

The payload is base64 encoded when sent to the webhook endpoint.

Request sample sent to the webhook endpoint:

{
    "headers": {
        "Accept-Encoding": "gzip",
        "Host": "<webHook url>",
        "User-Agent": "EnterpriseEdgeGatewayDiscoveryAgent/<agent_version>",
        "Contenttype": "application/json",
        "Content-Length": "485"
    },
    "body": {
        "$content-type": "application/octet-stream",
        "$content": "eyJjYXRhbG9nSXRlbUlkIjoiZTRlOTFkMjM3NDRiY2I0ZDAxWFhYWCIsImNhdGFsb2dJdGVtVXJsIjoiaHR0cHM6Ly9hcGljZW50cmFsLmF4d2F5LmNvbS9jYXRhbG9nL2V4cGxvcmUvZTRlOTFkMjM3NDRiY2I0ZDAxWFhYWCIsImNhdGFsb2dJdGVtTmFtZSI6Ik1lZGljYWwgUHJhY3RpdGlvbmVyIChWNykiLCJhY3Rpb24iOiJBQ1RJVkUiLCJlbWFpbCI6InVzZXJAbWFpbC5jb20iLCJrZXkiOiI0OWQ5NzJjZC0wZjA2LTQ1MGMtODZkMS1YWFhYWFhYIiwia2V5SGVhZGVyTmFtZSI6IktleUlkIiwiYXV0aHRlbXBsYXRlIjoiWW91ciBBUEkgaXMgc2VjdXJlZCB1c2luZyBhbiBBUElLZXkgY3JlZGVudGlhbDpoZWFkZXI6XHUwMDNjYlx1MDAzZUtleUlkXHUwMDNjL2JcdTAwM2UvdmFsdWU6XHUwMDNjYlx1MDAzZTQ5ZDk3MmNkLTBmMDYtNDUwYy04NmQxLVhYWFhYWFhcdTAwM2MvYlx1MDAzZSJ9"
    }
}

API provider: subscription preparation

  1. (Optional) An API provider creates one or more applications on Axway API Manager and provides the necessary security feature (API key / OAuth…) and quota, if needed:

    • Add a custom field to the application to track the AMPLIFY Central subscription. Refer to <API_Gateway_install_dir>/apigateway/webapps//apiportal/vordel/apiportal/app/app.config file in the customPropertiesConfig section. For more details, see Customize API Manager.

      Sample application:

      customPropertiesConfig: {
              user: {
                  // custom properties...
              },
              organization: {
                  // custom properties...
              },
              application: {
                  subscriptions: {
                      label: 'Subscriptions'
                  },
              },
              api: {
                  // custom properties...
              }
          }
      
  2. (Optional) An API provider adds API access on the application(s) for each API they wish to allow their subscriber to subscribe to.

  3. (Optional) An API provider allows the consumer to create an application during the subscription flow (add the property APIMANAGER_ALLOWAPPLICATIONAUTOCREATION=true to the discovery agent configuration file).

API consumer: subscription workflow

  1. A consumer initiates the subscription in AMPLIFY Central:

    1. Open an AMPLIFY Catalog item.
    2. Click Subscribe.
    3. Select the Team and API Manager Application name for which you want to subscribe. For additional information, see Manage AMPLIFY Catalog subscriptions.
  2. Based on the API subscription approval (manual vs. automatic), an API provider has to approve the subscription.

  3. The Discovery Agent receives the subscription event:

    • subscription status: Active

      • Subscription ID is automatically added to the Custom field of the application.
      • Agent triggers credentials sending (either via email or via webhook).
      • If a failure occurs for any reason during the process, the subscription status is set to: Subscription failed. Refer to the Discovery Agent log for more information. You can delete the subscription and start again from Step 1.
  4. The subscriber consumes the API:

    • The API can be consumed once the API crendential details are received.

Workaround: You can grant the API access to the organization where the application belongs:

  1. In the UI, select the API.
  2. Expand Manage selected.
  3. Select Grant access.

Unsubscribe workflow

  1. A consumer initiates unsubscribe:

    1. Open the AMPLIFY Catalog and navigate to the Subscription tab.
    2. Unsubscribe from the active subscription. For additional information, see Manage AMPLIFY Catalog subscriptions.
  2. The Discovery Agent receives the Unsubscribe event:

    • The subscription ID is removed from the application’s Custom field.

Impact on subscription when unpublishing an API

  1. In API Manager, assume there is a FrontEnd API that is published, has been discovered by the Discovery Agent, and has an active subscription to it in AMPLIFY Central.

  2. A user in API Manager unpublishes that API.

  3. The Discovery Agent discovers the change and:

    • Initiates an unsubscribe to AMPLIFY Central for that Catalog item.
    • The subscription ID is removed from the application’s Custom field.
    • The subscription status is set to Unsubscribed.

Impact of subscription approval mode on subscription workflow

The configuration setting for central.subscriptions.approvalmode will affect the flow of getting a subscription approved. Allowed settings are manual, auto and webhook. Each of these settings are detailed below.

Manual approval mode

This is the default setting. In manual approval mode, the subscription approval flow is as follows:

  1. A consumer in AMPLIFY Central clicks on Subscribe.
  2. The subscription status moves to Waiting for approval….
  3. The subscription remains in this state until a user with appropriate permissions on AMPLIFY Central locates the subscription and clicks Approve.
  4. The subscription status moves to Subscribing.
  5. The Discovery Agent receives the event and sets the status to Active, or Subscribe failed if there is a failure to subscribe.

Auto approval mode

In auto approval mode, the subscription approval flow is as described at the top of this page:

  1. A consumer in AMPLIFY Central clicks on Subscribe.
  2. The subscription status moves immediately to Subscribing….
  3. The Discovery Agent receives the event and sets the status to Active, or Subscribe failed if there is a failure to subscribe.

Webhook approval mode

In webhook approval mode, the Discovery Agent must be configured with a webhook url, and any webhook headers and authentication secret that the webhook needs. Within the webhook, many things are possible. For example, the webhook could generate an email to notify someone that a subscription is awaiting approval. Or, the webhook could do the subscription approval. Assuming that the webhook is correctly configured and coded, the subscription approval flow is as follows:

  1. A consumer in AMPLIFY Central clicks on Subscribe.
  2. The subscription status moves to Waiting for approval….
  3. The webhook is notified of the event.
  4. The subscription remains in this state until the webhook moves the subscription to Approved, or a user with appropriate permissions on AMPLIFY Central locates the subscription and clicks Approve.
  5. The subscription status moves to Subscribing.
  6. The Discovery Agent receives the event and sets the status to Active, or Subscribe failed if there is a failure to subscribe.

Subscription failures

The agent could mark a subscription as Failed to subscribe or Failed to unsubscribe for any of the following reasons:

Failure Description Remediation
1 The API on API Gateway Manager is unpublished. Under the API section in API Manager > Manage the Frontend API: Publish the desired API.
2 On API Gateway Manager, the organization to which the application chosen for the subscription has not given API Access to the API, or the access has been given but has been disabled. Under the Clients section in API Manager > Organizations: Verify that the ORG has “Enabled” toggled correctly (under General) and that the API has been added (under API Access).
3 On API Gateway Manager, the application chosen for the subscription has not given API Access to the API, or the access has been given but has been disabled. Under the Clients section in API Manager > Applications > Application Tab: Verify that the APP has “Enabled” toggled correctly (under General) and that the API has been added (under API Access).
4 On API Gateway Manager, the application chosen for the subscription has not set up any authentication. Under the Clients section in API Manager > Applications > Authentication Tab: Verify that the APP has the appropriate authentication type setup.
5 On API Gateway Manager, the application chosen for the subscription does not match the inbound security setting for the API. Under the API section in API Manager > Manage the Frontend API, click the API > Inbound Tab: Verify that the API has the appropriate Inbound security selected.
6 The agent fails to communicate to API Gateway Manager. Check your internet connection. API Gateway Manager requires an HTTPS connection.

For additional information, see Manage AMPLIFY Catalog subscriptions.