Application Config

Every app must have exactly one defineApplication call. It declares:

Identity — universal identifier, display name, description.
Permissions — which role its logic functions and front components run under.
Media capabilities (optional): microphone or camera access requested by front components, approved separately from role permissions.
Variables (optional) — key–value pairs exposed to your code as environment variables.
Pre-install / post-install / uninstall hooks (optional) — see Logic Functions.
Billing (optional) — billing.recurring for subscription fees the platform raises automatically, billing.operations for what your app charges credits for, and billing.description for the marketplace; see Charging Credits.

src/application-config.ts

import { defineApplication } from 'twenty-sdk/define';

export default defineApplication({
  universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
  displayName: 'My Twenty App',
  description: 'My first Twenty app',
  applicationVariables: {
    DEFAULT_RECIPIENT_NAME: {
      universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
      label: 'Default recipient name',
      description: 'Default recipient name for postcards',
      value: 'Jane Doe',
      isSecret: false,
    },
    API_KEY: {
      universalIdentifier: '6b1f5a02-7c4d-4a19-9e63-2f0c8a5d1b47',
      label: 'API key',
      description: 'Key used to reach the postcard provider',
      isSecret: true,
      isRequired: true,
    },
  },
});

Notes:

universalIdentifier fields are UUIDs you generate once and own. Keep them stable across syncs. The application’s own universalIdentifier must be a valid UUID: the server rejects a manifest whose identifier is not one. It is unique across the whole instance and is bound to the workspace that owns its registration, so only that workspace can sync the app — see Registration ownership.
applicationVariables accept an optional label — a user-friendly name displayed in the app’s settings page instead of the raw variable key.
applicationVariables become environment variables for your functions and front components. In logic functions (server-side), they are available as process.env.VARIABLE_NAME. In front components, use getApplicationVariable('VARIABLE_NAME') from twenty-sdk/front-component. Variables marked with isSecret: true are only injected into logic functions. Front components receive only non-secret variables. A variable with scope: 'USER' holds the value of the member the code runs for: see Workspace and user variables.
Your app can also read and update its own variable values at runtime, which is how a custom settings component saves what the user typed: see Reading and updating variables at runtime. An application only ever reaches its own variables, in its own workspace.
The default role is detected automatically from the role file marked with defineApplicationRole() — you do not need to reference it from defineApplication().
Pre-install, post-install, and uninstall functions, and the health check, are detected automatically during the manifest build — you do not need to reference them in defineApplication().
Passing defaultRoleUniversalIdentifier explicitly is still supported for backward compatibility, but is deprecated in favor of defineApplicationRole().
serverVariables are instance-scoped configuration and secrets (e.g. API keys). Unlike applicationVariables, they declare no value in the manifest — the workspace operator fills them in from the app’s settings, and they are injected into logic functions only once set.
An app can report its own configuration state with defineHealthCheck(), for what only the app can know — a key that is present but revoked, a third-party account on the wrong plan. isRequired covers what Twenty can see by itself; the health check covers the rest.
Both kinds of variable accept isRequired: true. A required variable the workspace has not filled in yet leaves the app unconfigured: its settings page shows a banner naming the missing variables, with a button that jumps to the tab where they are set. Mark as required only what the app genuinely cannot run without — an optional variable with a sensible default should stay optional.
Both kinds of variable accept isDeprecated: true. Use it to retire a variable instead of deleting it: keeping the key declared preserves the stored value (deleting it destroys the value the operator entered), and the variable is still injected, so your code can fall back to it — process.env.NEW_API_KEY ?? process.env.API_KEY. A deprecated variable disappears from the app’s settings once it has no value, and never counts toward the app’s configuration check, so isDeprecated beats isRequired.
Twenty sets these names for every logic function run, so they are reserved: TWENTY_API_URL, TWENTY_APP_ACCESS_TOKEN, TWENTY_APP_APPLICATION_ACCESS_TOKEN, TWENTY_API_KEY, TWENTY_FUNCTIONS_URL and APPLICATION_ID. A manifest that declares one of them as an application or server variable is rejected when the app is synced or published.
To add your own entries to the app’s settings menu (in place of the generated Variables page), declare a front component and point a defineSettingsMenuItem() at it, in its own file. Declare as many as you need and order them with position; scope puts an item under the workspace settings or under each member’s own settings. The system-managed General item (auto-upgrade, App URL, connections) always comes first, and App URL only shows when the app has HTTP-triggered functions.

Requested media capabilities

Set requestedCapabilities when a front component uses navigator.mediaDevices.getUserMedia(). The optional array accepts 'microphone', 'camera', or both. Omit it or use an empty array when the app does not need media capture.

import { defineApplication } from 'twenty-sdk/define';

export default defineApplication({
  universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
  displayName: 'Media recorder',
  description: 'Record audio and video in your workspace',
  requestedCapabilities: ['microphone', 'camera'],
});

Declared capabilities appear during installation. Approval requires a workspace member who can manage apps and applies to the whole workspace. These grants are separate from the app’s role permissions and do not replace browser or operating system permissions. An installed app without the required grant pauses capture and shows an approval dialog on first use, including older apps without capability declarations. Declining leaves capture blocked before browser permissions are requested. Package updates do not automatically grant additional access. Locally synced development apps receive the capabilities declared in their manifest. See Media capture for capture behavior and recording indicators.

Variable types

Both applicationVariables and serverVariables accept an optional type (and, for SELECT / MULTI_SELECT, an options list). Supported types: TEXT (default), BOOLEAN, NUMBER, NUMERIC, DATE, DATE_TIME, SELECT, MULTI_SELECT, ARRAY, RAW_JSON, RICH_TEXT.

src/application-config.ts

import { defineApplication, FieldType } from 'twenty-sdk/define';

export default defineApplication({
  // ...identity, role...
  applicationVariables: {
    MAX_POSTCARDS: {
      universalIdentifier: '5f4497e4-9030-4085-85eb-2c48b8d53713',
      description: 'Maximum postcards per batch',
      type: FieldType.NUMBER,
      value: 10,
    },
    DEFAULT_REGION: {
      universalIdentifier: '76c5c321-b6b6-46eb-b4fc-f9f04bb04227',
      description: 'Default shipping region',
      type: FieldType.SELECT,
      options: [
        { label: 'Europe', value: 'eu' },
        { label: 'United States', value: 'us' },
      ],
      value: 'eu',
    },
  },
});

The type only affects presentation and validation — it selects the matching input in the workspace settings UI (a toggle, number field, dropdown, date picker, JSON editor, …) and lets the build validate your config (for example, SELECT / MULTI_SELECT must declare non-empty options). It does not change how the value reaches your code. Values are always injected as strings — this is inherent to environment variables (process.env.* is string-only). When your logic function runs, the executor serializes each value by its declared type while building process.env, so the string format is consistent no matter how the value was set (manifest default, settings UI, or a previous version):

Type	`process.env` string
`TEXT`, `SELECT`, `DATE`, `DATE_TIME`	the raw value (`"eu"`, `"2026-01-01"`)
`BOOLEAN`	`"true"` / `"false"`
`NUMBER`, `NUMERIC`	decimal string (`"10"`, `"2.5"`)
`MULTI_SELECT`, `ARRAY`	JSON array (`'["email","postcard"]'`)
`RAW_JSON`, `RICH_TEXT`	JSON object (`'{"retries":3}'`)

Parse the string back into the type you expect:

const maxCards = Number(process.env.MAX_POSTCARDS); // "10" -> 10
const enabled = process.env.ENABLE_TRACKING === 'true'; // "true" -> true
const channels = JSON.parse(process.env.ENABLED_CHANNELS ?? '[]'); // '["email"]' -> ["email"]
const config = JSON.parse(process.env.PROVIDER_CONFIG ?? '{}'); // '{"retries":3}' -> { retries: 3 }

The same applies to front components reading values via getApplicationVariable('VARIABLE_NAME') — the returned value is a string; parse it as needed.

Workspace and user variables

Each application variable has a scope:

WORKSPACE (default): one value for the whole workspace, set by a member who can manage apps.
USER: each member keeps their own value.

src/application-config.ts

import { defineApplication, FieldType } from 'twenty-sdk/define';

export default defineApplication({
  // ...identity, role...
  applicationVariables: {
    RECORD_MY_MEETINGS: {
      universalIdentifier: '0b6f3c1e-8a2d-4f57-9c1b-7e4d2a9f6c30',
      label: 'Record my meetings',
      type: FieldType.BOOLEAN,
      value: true,
      scope: 'USER',
    },
  },
});

A user variable’s value is its default: a member who has not set their own reads it, and a new version of your app can change it. A secret variable cannot have a default. Without one, a member who has not set theirs reads an empty string, so your app decides what an unset value means. A workspace admin cannot set a value for a user variable: its values belong to each member. A variable’s scope is set when it is created and cannot change. To change it, declare the variable with a new universalIdentifier: the sync deletes the old variable, with its members’ values, and creates the new one. User variables can be isSecret, isRequired, or both. For example, a personal API key can declare scope: 'USER', isSecret: true, isRequired: true. Values are encrypted at rest. For user variables, isRequired describes a per-member requirement. A member with no value for it, their own or a default, sees your app marked Missing configuration in App preferences, with a banner naming the variables. It does not affect the workspace configuration warning, and nothing enforces it at runtime: your code still decides what an unset value means. A user variable is injected with the value of the member your code runs for, or its default until they set their own:

In a logic function, process.env holds the values of the member who triggered the run, the same member TWENTY_APP_ACCESS_TOKEN acts as. A run with nobody behind it, such as a cron job or an install hook, gets no user variables at all.
In a front component, getApplicationVariable returns the values of the member viewing it. Secret user variables are left out, like secret workspace variables.

The member who triggered a run is not always the member it is about: a database event runs as whoever edited the record. When a run is about someone else, or about every member, read the values with myUserApplicationVariables through MetadataApiClient. It lists every member with their values of your app’s user variables, and works in every logic function run, including cron jobs and webhooks. Each entry carries the member’s userWorkspaceId, workspaceMemberId and variables: each user variable’s declaration (label, description, type, options, isSecret, isRequired, isDeprecated) and the member’s value, or the default until they set their own. Query it as the application to get real values: with a token that has a person behind it, it only returns that person’s entry, with secrets masked.

import { MetadataApiClient } from 'twenty-client-sdk/metadata';

// In a logic function, for example a cron job
const client = new MetadataApiClient({ runAs: 'application' });

const { myUserApplicationVariables } = await client.query({
  myUserApplicationVariables: {
    workspaceMemberId: true,
    variables: { key: true, value: true },
  },
});

Values are strings, in the same format as process.env (see Variable types). updateMyUserApplicationVariable saves a member’s own value. It takes your app’s applicationUniversalIdentifier and writes the value of the person behind the token: the member’s own session, or your app’s token when a member is behind it, such as in a front component or a logic function run for a member. Your app’s token can only name your own app, and a token with nobody behind it, such as in a cron job or an install hook, is refused. An empty value removes the member’s own value, so they read the default again, or an empty string for a variable without one. It needs no APPLICATIONS permission, but it needs CONNECTED_ACCOUNTS: on the member’s role, and, when your app’s token makes the call, on your app’s default role too, if it declares one. If your app saves user variables, add SystemPermissionFlag.CONNECTED_ACCOUNTS to permissionFlagUniversalIdentifiers in its role.

Default function role

The role declared with defineApplicationRole() controls what the app’s logic functions and front components can access:

The runtime tokens injected into your logic functions are derived from this role. A call acting as a person is further narrowed to what that person can do, so it can never exceed either one. See Whose access a call uses.
The typed API client is restricted to the permissions granted to that role.
Follow least-privilege: declare only the permissions your functions need.

When you scaffold a new app, the CLI creates a starter role file at src/roles/default-role.ts. See Roles & Permissions for the full reference.

Marketplace metadata

If you plan to publish your app, these optional fields control how it appears in the marketplace:

Field	Description
`author`	Author or company name
`category`	App category for marketplace filtering
`logo`	Path to your app logo bundled in `public/` (e.g., `public/logo.png`)
`galleryImages`	Array of gallery image paths bundled in `public/` (e.g., `public/screenshot-1.png`)
`aboutDescription`	Longer markdown description for the “About” tab. If omitted, the marketplace uses the package’s `README.md` from npm. Images do not render, and raw HTML shows as plain text
`billing.description`	What the app costs, in one short friendly line for your marketplace listing (e.g. `$0.02 per minute recorded`). Set it if your app charges credits
`websiteUrl`	Link to your website
`termsUrl`	Link to terms of service
`emailSupport`	Support email address
`issueReportUrl`	Link to issue tracker

logoUrl and screenshots are deprecated aliases of logo and galleryImages. External absolute URLs (http:// or https://) are not supported for these fields: they are dropped with a warning at build time. Bundle the images in your app’s public/ folder instead.

Overview

Apps

API

Self-Host

Contribute

UI Library

Requested media capabilities

Variable types

Workspace and user variables

Default function role

Marketplace metadata

​Requested media capabilities

​Variable types

​Workspace and user variables

​Default function role

​Marketplace metadata

Requested media capabilities

Variable types

Workspace and user variables

Default function role

Marketplace metadata