--- title: "Key Concepts" url: https://docs.catalyst.zoho.com/en/cloud-scale/help/api-gateway/key-concepts/ description: "Catalyst API Gateway enables you to create APIs to access the functions and web client end-points of your app, and perform advanced API management." last_updated: 2026-08-28T06:26:16Z service: Cloud Scale type: general --- # Key Concepts Before you learn about API Gateway's architecture and implementation, it's important to understand its fundamental concepts in detail. ### API Gateway vs Security Rules Catalyst API Gateway is an enhancement to [Catalyst Security Rules](https://docs.catalyst.zoho.com/en/serverless/help/security-rules/introduction) as it provides additional features for API management. Points to remember: * You can enable or disable the API Gateway at any time. * When the API Gateway is disabled, the configurations defined for a Catalyst function in Security Rules will be followed by default. * When you enable API Gateway for your Catalyst application, Security Rules will be disabled automatically. * After you enable API Gateway, the URLs of your functions and web client will immediately become inaccessible until you create APIs for them. Therefore, if you enable API Gateway, you must create APIs for all your functions and web client. * You can migrate the configurations of your functions in Security Rules to API Gateway using [auto-create](https://docs.catalyst.zoho.com/en/cloud-scale/help/api-gateway/key-concepts/#auto-created-apis-custom-apis-and-the-default-api). The differences between Security Rules and API Gateway are specified below:
Security Rules API Gateway
Can configure access for GET, PUT, POST, DELETE, and PATCH HTTP methods Can configure access for GET, GET, PUT, POST, DELETE, and PATCH HTTP methods. Can also aggregate all HTTP methods under ANY, and create a single API for it.
Request URL and Target URL are the same Can configure custom Request URL and Target URL separately. Can create individual APIs for each request method for every URL
Can enable or disable authentication and configure two types of authentication: Catalyst Users Authentication, and OAuth-based Authentication Can enable or disable authentication and configure three types of authentication: API Key, Catalyst Users Authentication, and OAuth-based Authentication
No throttling feature Can configure two types of throttling: General Throttling and IP-based Throttling
Cannot configure rules for web clients Can create APIs for web clients
### Routing The primary purpose of an API Gateway is to route the client to the appropriate services. This is defined by two aspects of an API: Request and Target. If an API has not been configured for a particular request method or request URL, the client will not be able to access the target. Let's learn about these in detail. #### Request Methods Catalyst API Gateway supports the following HTTP request methods: * **`GET`** * **`PUT`** * **`POST`** * **`DELETE`** * **`PATCH`** You can also aggregate all these HTTP methods under a custom defined method: `ANY`. This enables you to create a single API for a function that supports all five methods, instead of creating five individual APIs, one for each method. `ANY` can be used both in [auto-create and creating custom APIs](https://docs.catalyst.zoho.com/en/cloud-scale/help/api-gateway/key-concepts/#auto-created-apis-custom-apis-and-the-default-api). > **Note:** Web client APIs do not support `ANY`. You can only select the `GET` method for a web client. #### Request URL The URL of your Catalyst application has the following structure: https://_project\_domain\_name_.catalystserverless.com. When you create an API, you can define the request path and it will be automatically appended to this URL. This will be the request URL. For example, if the request path is _/CustomerPortal/create_, it will be appended to the application URL of that project, and the following request URL will be created: **https://shipmenttracking-61317105.catalystserverless.com/CusomerPortal/create**. You can then provide this intermediary request URL to the client, instead of the target function's or web client's default URL. The API that will then route this request URL to the configured target automatically. #### Target and Target URL As mentioned before, the target components of an API configured in API Gateway can be: Basic I/O functions, Advanced I/O functions, web client. You can set one target for every API that you create in API Gateway. You can create multiple APIs for each target for different request methods. > **Note:** API Gateway does not handle client requests for [Cron Functions and Event Functions](https://docs.catalyst.zoho.com/en/serverless/help/functions/event-functions) as they cannot be directly executed by end users. The URL format of each target is as follows: * **Basic I/O:** https://_project\_domain\_name_.catalystserverless.com/baas/v1/ project/_project\_ID_/function/_function\_ID_/execute * **Advanced I/O:** https://_project\_domain\_name_.catalystserverless.com/server/_function\_name_/ * **Web Client:** https://_project\_domain\_name_.catalystserverless.com/app/ You can append routes to an Advanced I/O function's or web client's target URL and create APIs for specific paths. #### Using Regular Expressions (Regex) in the Request URL and Target URL Catalyst offers support for regular expressions to hold dynamic values in the request URL. A **regular expression (regex)** is a sequence of characters that describes a search pattern. When you include a regex pattern in the request URL, pattern-matching, and search-and-replace algorithms are executed when the input value is provided during execution and the pattern is replaced with the dynamic value. You can enter a regex pattern in the JSON format in the request URL and pass the key to the target URL like: **Request url:** /route/{path:\[0-9\]+} **Target url:** /route/{path} For example, if the dynamic value of a request URL contains a string of numbers, you can use the expression _\[0-9\]+_. This indicates that the characters inside the brackets in the dynamic value can be any span of numbers from 0-9 and the `**+\***` indicates one or more occurrences of the digits. Therefore, the request URL here could be configured as: _**/CustomerPortal/{portalID:\[0-9\]+}**_. Now, if you append a route to the target URL of an Advanced I/O function as: _**/server/adIOFunc/CustomerPortal/{portalID}**_, the ID provided by the user in the request URL while accessing it will be dynamically passed to the target Advanced I/O function. You can also use a wildcard pattern in your regular expression, such as `\.` ,which indicates that any number of literal characters or an empty string can be accepted in the place of the wildcard pattern. For example, if you provide a wildcard pattern in the request URL like: **/CustomerPortal/{path:(.\*)}**, the user will be able to enter any value dynamically in the URL such as: _/CustomerPortal/johndoe12_, _/CustomerPortal/premiumUser/12809021_, or _/CustomerPortal/xae89013_. If you defined a regex pattern in the URL for an Advanced I/O function in [Security Rules](https://docs.catalyst.zoho.com/en/serverless/help/security-rules/introduction), the same pattern will be added to both the request URL and target URL during [auto-create](https://docs.catalyst.zoho.com/en/cloud-scale/help/api-gateway/key-concepts/#auto-created-apis-custom-apis-and-the-default-api). ### Authentication Request Processor The Request Processor handles the authentication of the API. Authentication is an optional feature in API Gateway. If you select `No Authentication` while creating the API, the target will be universally accessible to every client. > **Note:** The authentication feature is not available for web client APIs. It is only available for the Basic I/O and Advanced I/O functions. API Gateway supports three authentication methods. You can enable any or all of these methods. #### API Key This authentication is handled by an API key that is generated by Catalyst automatically for your project. The API Key is the same for all projects in the development environment. When you [deploy a Catalyst project to the Production environment](https://docs.catalyst.zoho.com/en/deployment-and-billing/environments/production-environment), Catalyst will provide you a different API key. You will therefore have individual API keys for each project in the Production environment. You can obtain the API key after you [create an API](https://docs.catalyst.zoho.com/en/cloud-scale/help/api-gateway/implementation/#create-an-api) for a Basic I/O or Advanced I/O function in your project, with the API Key authentication option enabled. Click **View API Key** in the API details section to access the key. ![catalyst_apig_api_key](https://catalyst-docs-development.zohostratus.in/images/help/api-gateway/catalyst_apig_api_key.webp) A pop-up window will open with the API key. ![catalyst_apig_api_key_2](https://catalyst-docs-development.zohostratus.in/images/help/api-gateway/catalyst_apig_api_key_2.webp) You can pass the API key in two ways: * **Request Header** You can pass the API key as a header in the request URL as shown in this example: ```bash curl -X POST \ https://shipmenttracking-61317105.catalystserverless.com/CustomerPortal/create \ -H "ZCFKEY: API_KEY" ``` * **Query String** You can also pass the API key as a query parameter in the request URL as shown in this example: ```bash POST https://shipmenttracking-61317105.catalystserverless.com/CustomerPortal/ create?ZCFKEY=API_KEY ``` Replace `API\_KEY` with your API key in both places. #### Catalyst Users Authentication This authentication method enables access for all the users of your Catalyst application added in the _Users_ section of [Catalyst Authentication](https://docs.catalyst.zoho.com/en/cloud-scale/help/authentication/introduction), by default. You can handle this authentication method by incorporating a user sign-in form in your Catalyst application, and enabling a login session. The [app users](https://docs.catalyst.zoho.com/en/cloud-scale/help/authentication/user-management/users/introduction/) will then be able to access the API's target automatically without needing to go through any additional user verification. #### OAuth-Based Authentication This authentication method enables access for the users with an OAuth access token. You can pass the access token as a header in the request URL as shown in this example: ```bash curl -X POST \ https://shipmenttracking-61317105.catalystserverless.com/CustomerPortal/create \ -H "Authorization: Zoho-oauthtoken Zoho-oauthtoken 1000.910*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*16.2f*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*57"" ``` To implement OAuth authentication in your Catalyst application, refer to our [OAuth Authentication help documentation](https://docs.catalyst.zoho.com/en/api/oauth2/overview-and-terminology/#OverviewandTerminology) for detailed steps. > **Note:** When implementing OAuth protocols for API Gateway access, you need to be aware of this behaviour. Depending on your user type, the following applies: * **Authenticated Users** can access your functions directly without any additional configuration. * **You and your Collaborators**, in addition to providing your OAuth token, must include the following request header to access your functions: * **Key:** `ZC-OAUTH-USER` * **Value:** `ADMIN` ### Throttling Throttling enables you to set a rate limit to control the usage of an API by the clients. Throttling is an optional feature in Catalyst API Gateway. When you set throttling rate limits for an API, Catalyst will monitor the count of request hits made to that API. When the request submissions exceed the limits you have configured for the API, the API Gateway will return the HTTP error response: `429 Too Many Requests`. There are two types of throttling available in API Gateway. You can use either one or both methods. #### General Throttling General throttling defines the maximum hits allowed to the API for all users, per time unit. You can define the request limit, its rate, and the time unit while creating the API. Catalyst implements a sliding window rate limiting algorithm where the window starts from the current element and shifts by a weighted value of the previous window's request rate. For example, if you set 50 requests in 2 minutes as the limit, Catalyst will check for API hits in the 2 minutes preceding the current second and determine the count, instead of checking in a 2 minute fixed window length. #### IP-Based Throttling IP-based throttling defines the maximum number of hits allowed to the API from a particular IP address, per time unit. This limits the number of API calls that can be made from a particular client address. You can define the request limit, its rate, and the time unit for this in a similar way as for general throttling. ### Auto-Created APIs, Custom APIs, and the Default API You can [create APIs for your Catalyst functions and web client](https://docs.catalyst.zoho.com/en/cloud-scale/help/api-gateway/implementation/#create-an-api) in two ways: auto-create or custom. Before we discuss auto-created APIs and custom APIs, you must learn about the default API. #### The Default API API Gateway creates a default API called `Login Redirect` for the web client hosted in your Catalyst project, in addition to the regular web client API. The following rules apply for the `Login Redirect` API: * This API is created when you create APIs in the API Gateway for the first time after hosting a web client in your Catalyst project, using either auto-create or the custom method. * The `Login Redirect` API is created based on the configuration set in the [client-package.json](https://docs.catalyst.zoho.com/en/cli/v1/project-directory-structure/client-directory/) file for the web client. The URL configured as the `login\_redirect` in that file will be set as the request URL and target URL of the API. The `login\_redirect` key is optional. Therefore, if it is not configured, the URL provided as the `homepage` will be set as the request URL and target URL. * If the URL configured as `login\_redirect` starts with a '/', Catalyst will consider it as an absolute path and will append it to the domain directly. For example, if `login\_redirect` is '**/home.html**', the request URL will be of the format: **https://_project\_domain\_name.catalystserverless_.com/home.html**. However, if the `login\_redirect` value does not start with a '/', such as '**home.html**', then the request URL will be of the format: **https://_project\_domain\_name_.catalystserverless.com/app/home.html**. * The values for general throttling and IP-based throttling for this default API will be set to `Not configured`, and the value for authentication will be set to `No authentication`. * You must give the default login redirect page of the Catalyst application as the request URL for the `Login Redirect` API. You must not give any other URL as its value. * If you change the value of `login\_redirect` in the `client-package.json` file after the `Login Redirect` API was created, the target URL value will be automatically changed when you deploy the client package to the Catalyst console. * You will not be able to edit any of these default values except the request URL. You will not be able to modify the target URL, API name, authentication, or throttling parameters. * You will not be able to delete the `Login Redirect` API. * The difference between the default `Login Redirect` API and the regular web client APIs is that, the `Login Redirect API` is only meant for the default login redirect page of the application where the users are redirected to, after they login. However, you can append routes to a web client's target URL and create APIs for different routes for regular web client APIs. * If you have not hosted a web client in your Catalyst project, this API will not be created. #### Auto-Created APIs You can enable Catalyst to automatically create APIs for the functions that you choose, or for the web client, using the auto-create method. Auto creating APIs is only available until you create your first API in API Gateway. Auto-create can be used when you have a large number of functions configured in your Catalyst project, and creating individual APIs for each of them would be very time consuming. When you use auto-create to create APIs, these protocols are followed: * If you have configured definitions for your functions in [Security Rules](https://docs.catalyst.zoho.com/en/serverless/help/security-rules/introduction), they will be migrated to API Gateway automatically during auto-create. If you have not configured any definitions, the default rules will be applied. * The APIs created for a function during auto-create will contain the HTTP methods and authentication configured for it in the Security Rules. * **Request methods and URL:** * If all five HTTP methods (`GET`, `PUT`, `POST`, `DELETE`, `PATCH`) are enabled for a function in Security Rules, a single API will automatically be created with the request method '[ANY](https://docs.catalyst.zoho.com/en/cloud-scale/help/api-gateway/key-concepts/#routing)' for the function. * If one or more of the five HTTP methods is disabled for a function in Security Rules, individual APIs will be created for each of the other methods. * The request URL of a function will be the same as its default target URL or the [function URL](https://docs.catalyst.zoho.com/en/serverless/help/functions/introduction) in auto-create, since the request URL and target URL are the same in Security Rules. * If there is a [regex pattern in the request URL](https://docs.catalyst.zoho.com/en/cloud-scale/help/api-gateway/key-concepts/#routing#) of a function, the same pattern will be assigned to the target URL. * **Authentication:** * If the authentication method for a function in Security Rules is `optional`, the [request processor](https://docs.catalyst.zoho.com/en/cloud-scale/help/api-gateway/key-concepts/#authentication-request-processor) will automatically be set to `No Authentication` for the function's APIs during auto-create. * If authentication for a function in Security Rules is enabled, Catalyst Users Authentication and OAuth-based Authentication will be automatically enabled for the function's APIs in API Gateway. * **Throttling:** The values for general throttling and IP-based throttling for a function's APIs will be set to `Not configured` by default during auto-create. * **API name:** An API created using auto-create for a function will be named in the format: _FunctionName\_HTTPMethod_. An API created for a web client using auto-create will be named in the format: _WebclientName_. * **Web client API:** The values for general throttling and IP-based throttling for a web client will be set to `Not configured`. As mentioned, earlier authentication is not available for web client APIs. The request URL of a web client will also be the same as its target [web app URL](https://docs.catalyst.zoho.com/en/cloud-scale/help/web-client-hosting/implementation#host-a-web-application). * **Hard limits:** The hard limit for the number of APIs that can be created is 1000 APIs/project. After the APIs are created for your functions and web client using auto-create, you can [edit individual APIs](https://docs.catalyst.zoho.com/en/cloud-scale/help/api-gateway/implementation/#edit-an-api) and modify the default values as required. #### Custom API You can create a custom API for your function or web client at any time and configure the parameters of the API. You can define the request method and URL, the target, authentication methods, throttling, and more based on your requirements. Creating a custom API does not migrate the configurations of a function from Security Rules.