Articles in this section

Create and manage API plans, applications, and subscriptions

Kathyana Queeman
Updated

Before you begin, learn more about API management. You should also be familiar with plans, applications, and subscriptions.

This guide is for API publishers who create and manage plans, as well as approve subscriptions. To subscribe to and use a published API, see API consumers.

Note: Several paths in this article depend on your API definition version. v4 APIs use the current console layout; v2 APIs use the legacy layout. Learn more about API definitions.

Create your API plans

A default API plan is created when you publish the API through integrator.io. However, you can create other tiered plans to manage options like rate limiting and quotas. You can also customize plan-level flows in the Policies section (v4) or the Policy Studio's Design tab (v2). Learn more about plans.

consumers_plans.jpg

Create a plan for a v4 API

  1. Navigate to Consumers → Plans.

  2. Select Add new plan and choose the authentication type:

    1. OAuth2: OAuth2 can only be enabled using Identity and Access Management software (IAM).
    2. JWT: JWT only supports the RSA Public Key format.
    3. API keys: You use API key plans to enforce verification of API keys during request processing, allowing only apps with approved API keys to access your APIs. This plan type ensures that API keys are valid, are not revoked or expired, and are approved to consume the specific resources associated with your API. API key plans offer only a basic level of security, acting more as a unique identifier than a security token, since the API key can easily be found in the app code. For a higher level of security, see OAuth 2.0 and JWT plans. The API key header is x-celigo-api-key. You can find it at Settings → Settings → Portal.
    4. Keyless plans: Keyless plans allow public access to the API and bypass any security mechanisms on the whole request process. By default, keyless plans offer no security and are most useful for quickly and easily exposing your API to external users and getting their feedback. Due to the lack of a consumer identifier token (API key), keyless consumers are set as unknown application in the API analytics section.
    5. Push: Push plans apply to v4 message APIs with an entrypoint that sends message payloads to API consumers, such as a Webhook. The API consumer defines the security configuration — for example, the target URL and authentication for a Webhook — in the subscription request created in the Developer Portal.
    6. mTLS: mTLS plans require consumers to present a client certificate to connect to the API, providing two-way authentication between the consumer and the Gateway. Consumers add the certificate to their application at Global settings → Certificates.

    Note: The Push and mTLS options appear only if they're turned on at Settings → Settings under the Console heading.

  3. On the General stage, enter a Name (50-character limit) and Description. Optionally, add Characteristics and a Page of General Conditions.

    api_key_plan_edit.jpg
  4. Under Subscriptions, turn on Auto validate subscription to approve subscriptions automatically, or turn it off to approve each subscription manually. You can also require consumers to provide a comment when subscribing, and display a custom message.
  5. Optionally, assign Sharding tags under Deployment and exclude groups under Access-Control.
  6. On the authentication configuration stage (for example, API Key authentication configuration), configure the security settings for the plan type.
  7. Configure any restrictions, such as rate limiting, quota, and resource filtering, and save the plan.

Note: If you change the general conditions of a published plan, notify your API subscribers.

Create a plan for a v2 API

  1. Navigate to Your API → Plans.
  2. Select + to create a new plan.
  3. Set your Authentication type, described in the preceding v4 steps.
  4. Check scopes: Select the required scopes to access the resource. You can add scopes as needed.
  5. Set Rate limiting to limit how many HTTP requests an application can make in a given period of seconds or minutes.
  6. Set a Quota to limit how many HTTP requests an application can make in a given period of hours, days, or months.
  7. Configure Resource filtering to restrict resources according to whitelist or blacklist rules.

Publish your API plan

You must publish your API plan before anyone can subscribe to it. Don't forget to deploy your plan first to send the latest changes. To publish:

  1. Navigate to Consumers → Plans and select the Staging tab (v4), or Plans → Staging (v2).
  2. Select the publish icon (cloud with an arrow) for the plan.
  3. Confirm that you want your plan to be published.

In v4, published plans move to the Published tab.

Deprecate your plan

To deprecate your plan, select the deprecate icon (cloud with an X) for the plan and confirm that you want to deprecate the plan. In v4, deprecated plans move to the Deprecated tab.

Caution: A deprecated plan is no longer available on the Developer Portal, and new subscriptions to the plan cannot be created. Existing subscriptions are maintained.

Manage applications

Your applications allow you to consume your APIs. Generally, your API consumers would create an application in the API developer portal. Select an application to manage its Global settings, User and group access, Metadata, Subscriptions, Analytics, Logs, and Notification settings — see Navigate the APIM console for details on each.

Configure your application types

Before you or your users can create an application, you must configure your allowed application types.

  1. Navigate to Settings → Client Registration.

    settings_client_register.jpg
  2. Configure the Default application type.
  3. Under Allowed application types, turn on the types users can create: Browser, Web, Native, or Backend-to-Backend.
  4. Optionally, turn on Enable Dynamic Client Registration and add a provider.

Manage subscriptions

When you create new plans, you can specify auto-validation of subscriptions so API consumers can access the API as soon as they subscribe to the plan. If you use manual approval, you must manually approve all subscriptions.

For v4 APIs, manage a specific API's subscriptions at Consumers → Subscriptions, where you can filter by plan, application, status, or API key, export the list as a CSV, or create a subscription on a consumer's behalf.

consumers_subscriptions.jpg

Approve a subscription

When publishers create new plans, they can specify auto-validation of subscriptions so consumers can access the API as soon as they subscribe to the plan. If you set manual approval on a plan, however, you must approve subscriptions by following these steps.

  1. Open your API and select Consumers → Subscriptions (v4) or Portal → Subscription (v2).
  2. Select the pending subscription.
  3. Select Accept, then enter the start and end dates of subscription approval (no end date means forever).

Tip: Pending subscription requests also appear at Dashboard → My Tasks. Select Validate to review and approve them from there.

Revoke a subscription

You can revoke a subscription to remove access to APIs.

  1. Open your API and select Consumers → Subscriptions (v4) or Portal → Subscription (v2).
  2. Select the close action for the subscription you want to revoke, and confirm.

Related articles