Application Config

• Identity — universal identifier, display name, description.
• Permissions — which role its logic functions and front components run under.
• 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.

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,
    },
  },
});

• 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.
• 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 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.
• 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.
• To render a custom configuration UI as the app’s Settings tab (in place of the default Variables tab), declare a front component with defineSettingsFrontComponent() in its own file. Only one is allowed per app. System-managed sections (auto-upgrade, App URL, connections) stay in the app’s General tab.

​

Variable types

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',
    },
  },
});

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 }

​

Default function role

• 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.

​

Marketplace metadata