Skip to main content
Version: Config V2

Endpoints

The Proxy accepts HTTP requests on the following endpoints.

CDN Proxy​

The CDN proxy endpoint's purpose is to forward the underlying config JSON to other ConfigCat SDKs used by your application.

caution

Regarding the config JSON's schema changes introduced recently (v6), the v0.3.X and newer Proxy versions are providing the new schema on the CDN proxy endpoint. This new config JSON schema is only supported from certain SDK versions listed in the support table below. Those SDKs that are older than the listed versions are incompatible with v0.3.X, and can be used only with v0.2.X or older Proxy versions.

GETOPTIONS/configuration-files/configcat-proxy/{sdkId}/config_v6.json

This endpoint is mainly used by ConfigCat SDKs to retrieve all required data for feature flag evaluation.

Route parameters:

  • sdkId: The SDK identifier that uniquely identifies an SDK within the Proxy.

Responses:

  • 200: The config.json file is downloaded successfully.
  • 204: In response to an OPTIONS request.
  • 304: The config.json file isn't modified based on the Etag sent in the If-None-Match header.
  • 400: The sdkId is missing.
  • 404: The sdkId is pointing to a non-existent SDK.

SDK Usage​

In order to let a ConfigCat SDK use the Proxy, you have to set the SDK's baseUrl parameter to point to the Proxy's host. Also, you have to pass the SDK identifier prefixed with configcat-proxy/ as the SDK key.

So, let's assume you set up the Proxy with the following SDK option:

options.yml
sdks:
  my_sdk:
    key: "<your-sdk-key>"

The SDK's initialization that works with the Proxy will look like this:

example.js
import * as configcat from "configcat-js";

var configCatClient = configcat.getClient(
  "configcat-proxy/my_sdk", // SDK identifier as SDK key
  configcat.PollingMode.AutoPoll,
  { baseUrl: "http(s)://localhost:8050" } // Proxy URL
);

Supported SDK Versions​

The following SDK versions are supported by the >=v0.3.X Proxy's CDN endpoint:

SDKVersion
.NET>=v9.0.0
JS>=v9.0.0
JS SSR>=v8.0.0
React>=v4.0.0
Node>=v11.0.0
Python>=v9.0.3
Go>=v9.0.0
C++>=v4.0.0
Dart>=v4.0.0
Elixir>=v4.0.0
Java>=v9.0.0
Android>=v10.0.0
Kotlin>=v3.0.0
PHP 8.1+>=v9.0.0
PHP 7.1+>=v3.0.0
Ruby>=v8.0.0
Swift>=v11.0.0

Available Options​

The following CDN Proxy related options are available:

OptionDefaultDescription
http:
  cdn_proxy:
    enabled: <true|false>
trueTurns the hosting of the CDN proxy endpoint on/off. This endpoint can be used by other ConfigCat SDKs in your applications.
http:
  cdn_proxy:
    cors:
      enabled: <true|false>
trueTurns the sending of CORS headers on/off. It can be used to restrict access to specific domains. By default, the Proxy allows each origin by setting the Access-Control-Allow-Origin response header to the request's origin. You can override this functionality by restricting the allowed origins with the allowed_origins or allowed_origins_regex options.
http:
  cdn_proxy:
    cors:
      allowed_origins: 
        - https://domain1.com
        - https://domain2.com
-List of allowed CORS origins. When it's set, the Proxy will include only that origin in the Access-Control-Allow-Origin response header which matches the request's Origin.
When there's no matching request origin and the allowed_origins_regex option is not set, the Proxy will set the Access-Control-Allow-Origin response header to the first item in the allowed origins list.
http:
  cdn_proxy:
    cors:
      allowed_origins_regex:
        patterns:
          - https:\/\/.*domain1\.com
          - https:\/\/.*domain2\.com
-

List of regex patterns used to match allowed CORS origins. When it's set, the Proxy will match the request's Origin with the given regex patterns. When there's a match, the Access-Control-Allow-Origin response header will be set to the matched origin.
When there's no matching request origin, the Proxy will set the Access-Control-Allow-Origin response header to the if_no_match field's value.
The if_no_match option is mandatory if this option is used.
When using the environment variable, the regex escape character must be doubled (\\) because it's parsed as a JSON list and \ is also a JSON escape character.

http:
  cdn_proxy:
    cors:
      allowed_origins_regex:
        if_no_match: https://domain1.com
-Required when the previous patterns option is set. It's value is used in the Access-Control-Allow-Origin header when an incoming request's Origin doesn't match with any previously configured regex patterns.
http:
  cdn_proxy:
    headers:
      Custom-Header-Name: "<header-value>"
-Additional headers that must be sent back on each CDN proxy endpoint response.

API​

The API endpoints are for server side feature flag evaluation.

POSTOPTIONS/api/{sdkId}/eval

This endpoint evaluates a single feature flag identified by a key with the given User Object.

Route parameters:

  • sdkId: The SDK identifier that uniquely identifies an SDK within the Proxy.

Request body:

{
  "key": "<feature-flag-key>",
  "user": {
    "Identifier": "<user-id>",
    "Rating": 4.5,
    "Roles": ["Role1","Role2"],
    // any other attribute
  }
}

The type of the user object's fields can only be string, number, or string[].

Responses:

  • 200: The feature flag evaluation finished successfully.
    • Response body:
    {
      "value": <evaluated-value>,
      "variationId": "<variation-id>"
    }
  • 204: In response to an OPTIONS request.
  • 400: The sdkId or the key from the request body is missing.
  • 404: The sdkId is pointing to a non-existent SDK.
POSTOPTIONS/api/{sdkId}/eval-all

This endpoint evaluates all feature flags with the given User Object.

Route parameters:

  • sdkId: The SDK identifier that uniquely identifies an SDK within the Proxy.

Request body:

{
  "key": "<feature-flag-key>",
  "user": {
    "Identifier": "<user-id>",
    "Rating": 4.5,
    "Roles": ["Role1","Role2"],
    // any other attribute
  }
}

The type of the user object's fields can only be string, number, or string[].

Responses:

  • 200: The evaluation of all feature flags finished successfully.
    • Response body:
    {
      "feature-flag-key-1": {
        "value": <evaluated-value>,
        "variationId": "<variation-id>"
      },
      "feature-flag-key-2": {
        "value": <evaluated-value>,
        "variationId": "<variation-id>"
      }
    }
  • 204: In response to an OPTIONS request.
  • 400: The sdkId is missing.
  • 404: The sdkId is pointing to a non-existent SDK.
POSTOPTIONS/api/{sdkId}/refresh

This endpoint commands the underlying SDK to download the latest available config JSON.

Route parameters:

  • sdkId: The SDK identifier that uniquely identifies an SDK within the Proxy.

Responses:

  • 200: The refresh was successful.
  • 204: In response to an OPTIONS request.
  • 400: The sdkId is missing.
  • 404: The sdkId is pointing to a non-existent SDK.
GETOPTIONS/api/{sdkId}/keys

This endpoint returns all feature flag keys belonging to the given SDK identifier.

Route parameters:

  • sdkId: The SDK identifier that uniquely identifies an SDK within the Proxy.

Responses:

  • 200: The keys are returned successfully.
    • Response body:
    {
      "keys": [
        "feature-flag-key-1",
        "feature-flag-key-1"
      ]
    }
  • 204: In response to an OPTIONS request.
  • 400: The sdkId is missing.
  • 404: The sdkId is pointing to a non-existent SDK.

Available Options​

The following API related options are available:

OptionDefaultDescription
http:
  api:
    enabled: <true|false>
trueTurns the hosting of the API endpoints on/off. These endpoints can be used for server side feature flag evaluation.
http:
  api:
    cors:
      enabled: <true|false>
trueTurns the sending of CORS headers on/off. It can be used to restrict access to specific domains. By default, the Proxy allows each origin by setting the Access-Control-Allow-Origin response header to the request's origin. You can override this functionality by restricting the allowed origins with the allowed_origins or allowed_origins_regex options.
http:
  api:
    cors:
      allowed_origins: 
        - https://domain1.com
        - https://domain2.com
-List of allowed CORS origins. When it's set, the Proxy will include only that origin in the Access-Control-Allow-Origin response header which matches the request's Origin.
When there's no matching request origin and the allowed_origins_regex option is not set, the Proxy will set the Access-Control-Allow-Origin response header to the first item in the allowed origins list.
http:
  api:
    cors:
      allowed_origins_regex:
        patterns:
          - https:\/\/.*domain1\.com
          - https:\/\/.*domain2\.com
-

List of regex patterns used to match allowed CORS origins. When it's set, the Proxy will match the request's Origin with the given regex patterns. When there's a match, the Access-Control-Allow-Origin response header will be set to the matched origin.
When there's no matching request origin, the Proxy will set the Access-Control-Allow-Origin response header to the if_no_match field's value.
The if_no_match option is mandatory if this option is used.
When using the environment variable, the regex escape character must be doubled (\\) because it's parsed as a JSON list and \ is also a JSON escape character.

http:
  api:
    cors:
      allowed_origins_regex:
        if_no_match: https://domain1.com
-Required when the previous patterns option is set. It's value is used in the Access-Control-Allow-Origin header when an incoming request's Origin doesn't match with any previously configured regex patterns.
http:
  api:
    headers:
      Custom-Header-Name: "<header-value>"
-Additional headers that must be sent back on each API endpoint response.
http:
  api:
    auth_headers:
      X-API-KEY: "<auth-value>"
-Additional headers that must be on each request sent to the API endpoints. If the request doesn't include the specified header, or the values are not matching, the Proxy will respond with a 401 HTTP status code.

SSE​

The SSE endpoint allows you to subscribe for feature flag value changes through Server-Sent Events connections.

GETOPTIONS/sse/{sdkId}/eval/{data}

This endpoint subscribes to a single flag's changes. Whenever the watched flag's value changes, the Proxy sends the new value to each connected client.

Route parameters:

  • sdkId: The SDK identifier that uniquely identifies an SDK within the Proxy.
  • data: The base64 encoded input data for feature flag evaluation that must contain the feature flag's key and a User Object.

Responses:

  • 200: The SSE connection established successfully.
    • Response body:
    {
      "value": <evaluated-value>,
      "variationId": "<variation-id>"
    }
  • 204: In response to an OPTIONS request.
  • 400: The sdkId, data, or the key attribute of data is missing.
  • 404: The sdkId is pointing to a non-existent SDK.

Example:

example.js
const rawData = {
  key: "<feature-flag-key>",
  user: { // field types can only be `string`, `number`, or `string[]`.
    Identifier: "<user-id>",
    Rating: 4.5,
    Roles: ["Role1","Role2"],
    // any other attribute
  }
}

const data = btoa(JSON.stringify(rawData))
const evtSource = new EventSource("http(s)://localhost:8050/sse/my_sdk/eval/" + data);
evtSource.onmessage = (event) => {
  console.log(event.data); // {"value":<evaluated-value>,"variationId":"<variation-id>"}
};
GETOPTIONS/sse/{sdkId}/eval-all/{data}

This endpoint subscribes to all feature flags' changes behind the given SDK identifier. When any of the watched flags' value change, the Proxy sends its new value to each connected client.

Route parameters:

  • sdkId: The SDK identifier that uniquely identifies an SDK within the Proxy.
  • data: Optional. The base64 encoded input data for feature flag evaluation that contains a User Object.

Responses:

  • 200: The SSE connection established successfully.
    • Response body:
    {
      "feature-flag-key-1": {
        "value": <evaluated-value>,
        "variationId": "<variation-id>"
      },
      "feature-flag-key-2": {
        "value": <evaluated-value>,
        "variationId": "<variation-id>"
      }
    }
  • 204: In response to an OPTIONS request.
  • 400: The sdkId is missing.
  • 404: The sdkId is pointing to a non-existent SDK.

Example:

example.js
const rawData = {
  user: { // field types can only be `string`, `number`, or `string[]`.
    Identifier: "<user-id>",
    Rating: 4.5,
    Roles: ["Role1","Role2"],
    // any other attribute
  }
}

const data = btoa(JSON.stringify(rawData))
const evtSource = new EventSource("http(s)://localhost:8050/sse/my_sdk/eval-all/" + data);
evtSource.onmessage = (event) => {
  console.log(event.data); // {"feature-flag-key":{"value":<evaluated-value>,"variationId":"<variation-id>"}}
};

Available Options​

The following SSE related options are available:

OptionDefaultDescription
http:
  sse:
    enabled: <true|false>
trueTurns the hosting of the SSE endpoint on/off, This endpoint can be used to stream feature flag value changes.
http:
  sse:
    cors:
      enabled: <true|false>
trueTurns the sending of CORS headers on/off. It can be used to restrict access to specific domains. By default, the Proxy allows each origin by setting the Access-Control-Allow-Origin response header to the request's origin. You can override this functionality by restricting the allowed origins with the allowed_origins or allowed_origins_regex options.
http:
  sse:
    cors:
      allowed_origins: 
        - https://domain1.com
        - https://domain2.com
-List of allowed CORS origins. When it's set, the Proxy will include only that origin in the Access-Control-Allow-Origin response header which matches the request's Origin.
When there's no matching request origin and the allowed_origins_regex option is not set, the Proxy will set the Access-Control-Allow-Origin response header to the first item in the allowed origins list.
http:
  sse:
    cors:
      allowed_origins_regex:
        patterns:
          - https:\/\/.*domain1\.com
          - https:\/\/.*domain2\.com
-

List of regex patterns used to match allowed CORS origins. When it's set, the Proxy will match the request's Origin with the given regex patterns. When there's a match, the Access-Control-Allow-Origin response header will be set to the matched origin.
When there's no matching request origin, the Proxy will set the Access-Control-Allow-Origin response header to the if_no_match field's value.
The if_no_match option is mandatory if this option is used.
When using the environment variable, the regex escape character must be doubled (\\) because it's parsed as a JSON list and \ is also a JSON escape character.

http:
  sse:
    cors:
      allowed_origins_regex:
        if_no_match: https://domain1.com
-Required when the previous patterns option is set. It's value is used in the Access-Control-Allow-Origin header when an incoming request's Origin doesn't match with any previously configured regex patterns.
http:
  sse:
    headers:
      Custom-Header-Name: "<header-value>"
-Additional headers that must be sent back on each SSE endpoint response.
http:
  sse:
    log:
      level: "<error|warn|info|debug>"
warnThe verbosity of the SSE related logs.
Possible values: error, warn, info or debug.

Webhook​

Through the webhook endpoint, you can notify the Proxy about the availability of new feature flag evaluation data. Also, with the appropriate SDK options, the Proxy can validate the signature of each incoming webhook request.

GETPOST/hook/{sdkId}

Notifies the Proxy that the SDK with the given SDK identifier must refresh its config JSON to the latest version.

Route parameters:

  • sdkId: The SDK identifier that uniquely identifies an SDK within the Proxy.

Responses:

  • 200: The Proxy accepted the notification.
  • 400: The sdkId is missing or the webhook signature validation failed.
  • 404: The sdkId is pointing to a non-existent SDK.

ConfigCat Dashboard​

You can set up webhooks to invoke the Proxy on the Webhooks page of the ConfigCat Dashboard.

Webhook

Available Options​

The following webhook related options are available:

OptionDefaultDescription
http:
  webhook:
    enabled: <true|false>
trueTurns the hosting of the Webhook endpoint on/off. This endpoint can be used to notify the Proxy about the availability of new feature flag evaluation data.
http:
  webhook:
    auth:
      user: "<auth-user>"
-Basic authentication user. The basic authentication webhook header can be set on the Webhooks page of the ConfigCat Dashboard.
http:
  webhook:
    auth:
      password: "<auth-pass>"
-Basic authentication password. The basic authentication webhook header can be set on the Webhooks page of the ConfigCat Dashboard.
http:
  webhook:
    auth_headers:
      X-API-KEY: "<auth-value>"
-Additional headers that ConfigCat must send with each request to the Webhook endpoint. Webhook headers can be set on the Webhooks page of the ConfigCat Dashboard.