> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://contentful.com/developers/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/_mcp/server. # App Parameters > Use app parameters to separate code from configuration | What are parameters | Definitions ## What are parameters? > **Info** > > **WARNING**: Most parameters can be read by anybody who belongs to a space where your app is installed. Only parameters of type `Secret` should be used to inject access tokens. To privatize your parameters and ensure only your backend apps and Functions can access their raw values, configure [Secret installation parameters](#secret-installation-parameters) on your [`AppDefinition`](/extensibility/app-framework/app-definition). It's important to achieve separation of the code that forms your custom app and the configuration that is used by it. This way it can be shared, reused and reconfigured without any code changes. Below are some examples of the use cases for parameters: * Default values. * Project, category or entity identifiers when loading data from external APIs. * Slack channel name to post messages to. * Content types to process (e.g. for publishing content trees). * Kinds of validation to apply. The following types of configuration parameters can be set up: * **Installation parameters** — Are set during installation in a space environment and which can be modified in subsequent configuration updates. Their values are available across all usages of the app in the environment. * **Instance parameters** — Are set when a space member with access to the content model assigns an app to a [location](/extensibility/app-framework/locations). Values provided are available only in the specific location and content type where they were entered. ## Parameter definition **Parameter definition** is an object constructed as described in the table below. | Property | Type and value | Is required? | Remarks | | ------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------- | | `id` | String | yes | Can contain only letters, numbers and underscores | | `name` | String | yes | Human readable name of the parameter | | `description` | String | no | Further explanation of the purpose of the parameter | | `type` | String, one of `Symbol`, `Enum`, `Number`, `Boolean`, and if Installation `Secret` | yes | `Enum` parameters hold a predefined list of `Symbol`s | | `required` | Boolean | no, defaults to `false` | Whether the parameter value needs to be provided | | `default` | Should match `type` | no | Default value to use for the parameter. For `Enum`s it has to be defined on the `options` list | | `options` | List of allowed values: `["one", "two"]`; can be a list of `{"value": "Label"}` pairs to provide labels for values | yes | Applicable only to `Enum`s. `["x", "y"]` is equivalent to `[{"x": "x"}, {"y": "y"}]` | | `labels` | For `Enum`s: `{"empty": "Choose a value"}`; for `Boolean`s: `{"true": "sí", "false": "no"}` | no | Used for rendering a form. All labels are optional and have sensible defaults in English | ## Installation parameters ### Installation parameters use Installation parameters are set during the installation of an app in an environment and can be modified in subsequent configuration updates. Their values are available across all locations of the app in the environment. Installation parameters are used to customize an app depending on the environment it is installed in. Installation parameters are commonly used to set default values, to reference content types, or to configure the interaction of the app with third party services. #### Secret installation parameters Most installation parameter types can be read by every user with access to the space/environment where the app is installed. For sensitive installation parameters, we recommend using `Secret` type parameters, which are defined on your [`AppDefinition`](/extensibility/app-framework/app-definition). The raw values stored by the user in installation parameters whose keys match the IDs of these `Secret` parameter definitions will only be available when using [App Identities and Events](/extensibility/app-framework/app-identities-and-events) or [Functions](/extensibility/app-framework/functions). Secret installation parameters will be redacted both when accessed using the App SDK in the Contentful UI, and when using the Content Management API with a personal access token. ### Installation parameter definition Installation parameters have a limit of 32kB, and should be used responsibly to maximize editor performance. For flexibility, installation parameters do not have to be defined, if installation parameter definitions are omitted from your AppDefinition, they are stored in a free-form object. To maximize forward compatibility and opt in to the automatic parameter validation and privatization features provided by Contentful, configure definitions for your installation parameters just as you would for instance parameter definitions. Note that sensitive installation parameters should be of type `Secret`. Instance parameters can be defined as a part the [`AppDefinition`](/references/content-management-api/overview) entity: ```js { "name": "My parametrized backend app", "src": "https://myeditor.contentful.com", "locations": [{"location": "app-config"}], "parameters": { "installation": [ { "id": "apiKey", "type": "Secret", "name": "API Key", "description": "API Key for my backend app or function" } ] } } ``` > **Info** > > Hint: use the [create-app-definition](https://github.com/contentful/create-contentful-app/blob/8ef66e906d423cb7bd2184e75d802192aa12697c/packages/contentful--app-scripts/README.md#create-app-definition) script automatically available in any project created using the `create-contentful-app` CLI command to build your app and parameter definitions step-by-step straight from your terminal. ## Instance parameters ### Instance parameters use Instance parameters can be used to access user-provided values inside of app code. They are configurable per field where the app is installed. For instance parameters to be used in an app, the following prerequisites must be met: 1. Developers must enable the use of instance parameters by configuring the [`AppDefinition`](/extensibility/app-framework/app-definition) to define what types of values are to be expected. 2. Users configuring the app must provide the values of these parameters. To give an example of how instance parameters work, let's take a look at a list item app that is built to have the name of the list change based on what a user sets for that field. In the screenshot below, we are updating the content model for a specific content type. In this content type, the "List" field has an app called "List App" which is being used as the appearance. Instance parameters show up below the selected app and allow the user to input a custom value, in this case, the name of a list. ![instance parameters UI](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/contentful.docs.buildwithfern.com/b9b4f5693c84c23cc6ac5c7f618669ee3cdf0753fa2e776107f1e91b7f56544a/docs/assets/images/instance-parameters.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260929%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260929T230221Z&X-Amz-Expires=604800&X-Amz-Signature=b062a7ddcb2716bda4ec1d541d40470afcc97632a31e6a15af2c9e4fd7d19866&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) ### Instance parameter definition Up to 8 instance parameters can be defined as a part the [`AppDefinition`](/references/content-management-api/overview) entity: ```js { "name": "My parametrized editor app", "src": "https://myeditor.contentful.com", "locations": [{"location": "entry-editor"}], "parameters": { "instance": [ { "id": "helpText", "type": "Symbol", "name": "Help text", "description": "Help text for a user to help them understand the editor" }, { "id": "theme", "type": "Enum", "name": "Theme", "options": [{"light": "Solarized light"}, {"dark": "Solarized dark"}], "default": "light", "required": true } ] } } ``` You can define instance parameters for your app when [editing the `AppDefinition` in the web app](https://app.contentful.com/deeplink?link=app-definition): ![instance parameters UI](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/contentful.docs.buildwithfern.com/a6e8986a0f5933b67f594611f4aae0130cc924fef64375554bd76248806c070d/docs/assets/images/app-instance-param-ui.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260929%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260929T230221Z&X-Amz-Expires=604800&X-Amz-Signature=60441359d39bbf1eaf9e40b7f45def2c7f54072b45c36c8adfe98637e35bb5d1&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) Note that instance parameters cannot be of type `Secret`. ## Set and read parameter values Instance parameters are set in the [Editor Interface](/references/content-management-api/overview) entity. Installation parameters are provided as a top-level `parameters` property of the `Extension` entity: ```js { "parameters": { "devMode": true, "retries": 10 } } ``` Values, for both instance and installation parameters, can be read with the [App SDK](/extensibility/app-framework/sdk#configuration-of-an-extension-with-parameters): ```js init((sdk) => { console.log(sdk.parameters.instance); console.log(sdk.parameters.installation); }); ``` > **Info** > > Both `instance` and `installation` are guaranteed to be an empty object if values were not provided. > Use app parameters to separate code from configuration | What are parameters | Definitions