Various features are related to creating, managing, and using APIs. Before building an API, you should understand the key concepts surrounding Celigo's API management. This article discusses the main concepts and features of the APIM console. If you’re an API publisher creating an API, you should also learn more about navigating the API Management console. If you’re an API consumer, you should learn more about using the Developer Portal.
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.
API plans determine how consumers interact with your API. A plan provides a service and access layer on top of your APIs for consumer applications. You can create keyless plans with no authentication or tiered, authenticated plans. You can customize each plan with features like higher rate limits, additional endpoints, priority support, or advanced analytics.
There are four stages for plans:
- Staging – The plan has been created but isn’t available for subscribers yet. You can make changes to the plan and preview it.
- Published – The plan is active and available for subscribers.
- Deprecated – The plan is available to users who have already subscribed. New users cannot subscribe to the plan.
- Closed – The plan is closed and can’t be used by subscribers.
You can always change rate limits and quotas after you’ve created a plan.
With tiered plans, you can specify the authentication method — OAuth2, JWT, API key, Push, or mutual TLS (mTLS) — along with security features such as IP allowlisting or encrypted communications, and versioning.
Important:
All APIs published through integrator.io automatically have an API key plan.
The OAuth 2.0 authentication type checks access token validity during request processing using token introspection. If the access token is valid, the request proceeds. If not, the process stops and rejects the request. OAuth is an open standard that lets apps provide client applications with secure delegated access. It works over HTTPS and authorizes devices, APIs, servers, and applications with access tokens rather than credentials. You can enable OAuth2 only with Identity and Access Management (IAM) software.
The JWT authentication type ensures that third-party JWTs are valid. Only applications with approved JWTs can access APIs associated with a JWT plan.
JSON Web Tokens are an open standard for securely representing claims between two parties. JWTs are digitally signed using RSA public/private key pairs. JWT plans let you verify the JWT signature and check whether the JWT is still valid based on its expiry date.
JWT defines some registered claim names, including subject, issuer, audience, expiration time, and not-before time. In addition to these claims, the inbound JWT payload must include a client identifier claim (see the search order below) to link the JWT to the APIM application subscription. The policy searches for a client ID in the payload as follows:
- the
azpclaim - the
audclaim - the
client_idclaim
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. The API key header is x-celigo-api-key. For a higher level of security, see OAuth 2.0 and JWT plans.
When configuring API key authentication, there are two main options:
- Propagate API key to upstream API: Toggling this setting ensures the request to the backend API includes the API key header sent by the API consumer. This setting is useful for backend APIs with integrated API key authentication.
- Additional selection rule: This setting allows you to use Expression Language (EL) to filter by contextual data (request headers, tokens, attributes, etc.) for plans of the same type. For example, if you have two API key plans, you can set different selection rules on each plan to determine which plan handles each request.
Typically, API keys are randomly generated for each subscription. However, integrator.io provides two other options for API key generation: custom API key and shared API key. Both settings can be enabled at the environment level at Settings → Settings under the Portal heading.
You can specify a custom API key for an API key plan. This is particularly useful when you want to migrate silently to APIM and have a pre-defined API key. The custom API key must be URL compliant and have more than 8 characters and less than 64 characters. The following characters are invalid:
- #
- %
- @
- /
- ;
- =
- |
- ~
- ,
- <space>
When prompted, you can provide your custom API key or let APIM generate one by leaving the field empty. You can provide a custom API key when:
- Creating a subscription
- Accepting a subscription
- Renewing a subscription
Keyless plans allow public access to the API and bypass any security mechanisms during the 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 feedback. Due to the lack of a consumer identifier token (API key), keyless consumers are set as unknown applications in the API analytics section.
Push plans apply to v4 message APIs with an entrypoint that sends message payloads to API consumers, such as a Webhook. Unlike other plan types, the security configuration is defined by the API consumer in the subscription request created in the Developer Portal — for example, when subscribing to a Webhook entrypoint, the consumer specifies the target URL and the authentication the Gateway uses when sending messages. Push plans have the same configuration options as keyless plans. Push plans do not apply to Server-Sent Events entrypoints. Push plans must be turned on at Settings → Settings under the Console heading.
mTLS plans enforce the use of a client certificate to connect to the API, providing two-way authentication between the consumer and the Gateway. To subscribe to an mTLS plan, consumers add a certificate to their application at Global settings → Certificates. mTLS plans are available for v4 APIs only and must be turned on at Settings → Settings under the Console heading.
Your policies are customizable rules or logic the Gateway executes during an API transaction. Policies generally fall into security, transformation, performance, routing, or monitoring and testing categories. They are added to flows to enforce security, reliability, and proper data transfer. Examples of policies include traffic shaping, authentication/authorization, rate limiting, and dynamic routing. You can use dozens of policies; see the Policy Reference Guide for a comprehensive list.
For v4 APIs, you manage policies in the API's Policies section — a no-code tool for designing "flows," or policy enforcement sequences that protect, transform, or alter how your API is consumed. Flows are grouped by plan or as Common flows that apply at the API level. For v2 APIs, you use the Policy Studio, a drag-and-drop design tool. (For v4 APIs, properties and resources are managed in the API's Configuration section instead.)
Important:
- An APIM flow relates to the different phases of creating, managing, publishing, and subscribing to an API in APIM. This is not the same as a Celigo integrator.io flow.
- You do not have to create a flow to add a policy to the API. However, adding a flow allows you to better control what phases a policy is added to.
The Policy Studio's purpose and functionality are broken into the following sections:
- Design – Manage all flows associated with your Gateway API
- Configuration – Modify settings around flow execution
- Properties – Define key-value pairs at the API level. These properties are read-only during the Gateway's execution of an API transaction.
- Resources – Configure global resources to support your Gateway API's flows
You can create a flow and add one or more policies to the Request, Response, Publish, or Subscribe phases (Publish and Subscribe apply to v4 message APIs only). To learn more about a specific policy, see the APIM Policy Reference Guide. When a policy is applied and how it is enforced depends on the phase:
- Request phase – A policy is applied during the connection establishment. The Gateway enforces the policy at the time of the request before a client can access the API they are trying to call.
- Response phase – A policy is applied to the response from the initial connection. The Gateway enforces the policy after the request is allowed, but before the response is returned to the client.
- Publish phase – A policy is applied to messages sent to the endpoint. The Gateway enforces the policy when messages are published before clients can access the API they are trying to call.
- Subscribe phase – A policy is applied to messages received by the entrypoint. The Gateway enforces the policy after messages are subscribed to, but before the response is returned to the client.
You can create multiple policies for a single flow, each with a different configuration and applied to a different API phase. Flows can also be associated with specific plans or as common flows at the API level.
To access your APIs, consumers must register an application and subscribe to a published API plan (unless the plan is keyless). Applications act on behalf of the user to request tokens, provide user identity information, and retrieve protected resources from remote services and APIs. Typical applications are web applications, native applications, or batch/job applications that access data.
When a new application is created, only the creator (Primary Owner) can see and manage the application. Most of the time, an application is shared through a developer application and retrieves information such as API keys and API analytics.
By default, APIM includes three membership roles:
- Primary owner – When an application is created, the primary owner is the application's creator. The primary owner can do all possible actions for an application.
- Owner – The owner is the lightest version of the primary owner role. The owner can do all possible actions except delete the application.
- User – A user is a person who can access the application in read-only mode and use the application to subscribe to an API.
A subscription is a successful contract between an API publisher and an API consumer. Subscriptions are created when an API consumer uses a registered application to create a subscription request to a published plan, and an API publisher either manually or automatically validates the subscription. APIs with keyless plans do not require the API consumer to create an application or submit a subscription request, as no authorization is required to access the backend API.
After creating an application, API consumers can subscribe to APIs (with published plans) in the Developer Portal. The portal exposes published APIs so consumers can browse, request access, and use them. In the API Manager, API publishers can approve subscriptions to secure access and identify consumers for monitoring and analytics. For v4 APIs, publishers approve pending subscriptions at Consumers → Subscriptions, or from Dashboard → My Tasks. Learn more about managing subscriptions.
In most cases, integrator.io automatically generates your documentation. The main exception is JavaScript-based APIs, such as JavaScript API(s) imports or exports, which require you to generate your API specifications manually. Learn about best practices for creating documentation or learn more about using documentation provided by an API publisher.