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.

GETOPTIONS/configuration-files/{sdkId}/{config-json-file}

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.
• config-json-file: It's set by the ConfigCat SDK, it determines which config JSON schema must be used.

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 as the SDK key.

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

YAML

options.yml

sdks:
  my_sdk:
    key: "<your-sdk-key>"

Environment variables

CONFIGCAT_SDKS={"my_sdk":"<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(
  "my_sdk", // SDK identifier as SDK key
  configcat.PollingMode.AutoPoll,
  { baseUrl: "http(s)://localhost:8050" } // Proxy URL
);

Available Options

The following CDN Proxy related options are available:

Option	Default	Description
YAML http: cdn_proxy: enabled: <true|false> Environment variable CONFIGCAT_HTTP_CDN_PROXY_ENABLED=<true|false>	true	Enables or disables the CDN proxy endpoint, which can be used by ConfigCat SDKs in your applications.
YAML http: cdn_proxy: cors: enabled: <true|false> Environment variable CONFIGCAT_HTTP_CDN_PROXY_CORS_ENABLED=<true|false>	true	Enables or disables the sending of CORS headers. 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 next (allowed_origins) option.
YAML http: cdn_proxy: cors: allowed_origins: - https://domain1.com - https://domain2.com Environment variable CONFIGCAT_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, the Proxy will set the Access-Control-Allow-Origin response header to the first item in the allowed origins list.
YAML http: cdn_proxy: headers: Custom-Header-Name: "<header-value>" Environment variable CONFIGCAT_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>",
    "Email": "<user-email>",
    "Country": "<user-country>",
    // any other attribute
  }
}

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:

{
  "user": {
    "Identifier": "<user-id>",
    "Email": "<user-email>",
    "Country": "<user-country>",
    // any other attribute
  }
}

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:

Option	Default	Description
YAML http: api: enabled: <true|false> Environment variable CONFIGCAT_HTTP_API_ENABLED=<true|false>	true	Enables or disables the API endpoints, which can be used for server side feature flag evaluation.
YAML http: api: cors: enabled: <true|false> Environment variable CONFIGCAT_HTTP_API_CORS_ENABLED=<true|false>	true	Enables or disables the sending of CORS headers. 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 next (allowed_origins) option.
YAML http: api: cors: allowed_origins: - https://domain1.com - https://domain2.com Environment variable CONFIGCAT_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, the Proxy will set the Access-Control-Allow-Origin response header to the first item in the allowed origins list.
YAML http: api: headers: Custom-Header-Name: "<header-value>" Environment variable CONFIGCAT_HTTP_API_HEADERS='{"Custom-Header-Name":"<header-value>"}'	-	Additional headers that must be sent back on each API endpoint response.
YAML http: api: auth_headers: X-API-KEY: "<auth-value>" Environment variable CONFIGCAT_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: {
    Identifier: "<user-id>",
    Email: "<user-email>",
    Country: "<user-country>",
    // 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: {
    Identifier: "<user-id>",
    Email: "<user-email>",
    Country: "<user-country>",
    // 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:

Option	Default	Description
YAML http: sse: enabled: <true|false> Environment variable CONFIGCAT_HTTP_SSE_ENABLED=<true|false>	true	Enables or disables the SSE endpoint, which can be used for streaming feature flag value changes.
YAML http: sse: cors: enabled: <true|false> Environment variable CONFIGCAT_HTTP_SSE_CORS_ENABLED=<true|false>	true	Enables or disables the sending of CORS headers. 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 next (allowed_origins) option.
YAML http: sse: cors: allowed_origins: - https://domain1.com - https://domain2.com Environment variable CONFIGCAT_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, the Proxy will set the Access-Control-Allow-Origin response header to the first item in the allowed origins list.
YAML http: sse: headers: Custom-Header-Name: "<header-value>" Environment variable CONFIGCAT_HTTP_SSE_HEADERS='{"Custom-Header-Name":"<header-value>"}'	-	Additional headers that must be sent back on each SSE endpoint response.
YAML http: sse: log: level: "<error|warn|info|debug>" Environment variable CONFIGCAT_HTTP_SSE_LOG_LEVEL="<error|warn|info|debug>"	warn	The 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.

Available Options

The following webhook related options are available:

Option	Default	Description
YAML http: webhook: enabled: <true|false> Environment variable CONFIGCAT_HTTP_WEBHOOK_ENABLED=<true|false>	true	Enables or disables the Webhook endpoint, which can be used for notifying the Proxy about the availability of new feature flag evaluation data.
YAML http: webhook: auth: user: "<auth-user>" Environment variable CONFIGCAT_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.
YAML http: webhook: auth: password: "<auth-pass>" Environment variable CONFIGCAT_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.
YAML http: webhook: auth_headers: X-API-KEY: "<auth-value>" Environment variable CONFIGCAT_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.