UpdateOrganizationPolicies

POST/gitpod.v1.OrganizationService/UpdateOrganizationPolicies

Updates organization policy settings.

Use this method to:

Configure editor restrictions
Set environment resource limits
Define project creation permissions
Customize default configurations

Examples

Update editor policies:

Restricts available editors and sets a default.

organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
allowedEditorIds:
  - "vscode"
  - "jetbrains"
defaultEditorId: "vscode"

Set environment limits:

Configures limits for environment usage.

organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
maximumEnvironmentTimeout: "3600s"
maximumRunningEnvironmentsPerUser: "5"
maximumEnvironmentsPerUser: "20"

Body ParametersJSONExpand Collapse

organizationId: string

organization_id is the ID of the organization to update policies for

formatuuid

agentPolicy: optional object { commandDenyList, conversationSharingPolicy, maxSubagentsPerEnvironment, 3 more }

agent_policy contains agent-specific policy settings

commandDenyList: optional array of string

command_deny_list contains a list of commands that agents are not allowed to execute

conversationSharingPolicy: optional ConversationSharingPolicy

conversation_sharing_policy controls whether agent conversations can be shared

One of the following:

"CONVERSATION_SHARING_POLICY_UNSPECIFIED"

"CONVERSATION_SHARING_POLICY_DISABLED"

"CONVERSATION_SHARING_POLICY_ORGANIZATION"

maxSubagentsPerEnvironment: optional number

max_subagents_per_environment limits the number of non-terminal sub-agents a parent can have running simultaneously in the same environment. Valid range: 0-10. Zero means use the default (5).

formatint32

maximum10

mcpDisabled: optional boolean

mcp_disabled controls whether MCP (Model Context Protocol) is disabled for agents

scmToolsAllowedGroupId: optional string

scm_tools_allowed_group_id restricts SCM tools access to members of this group. Empty means no restriction (all users can use SCM tools if not disabled).

scmToolsDisabled: optional boolean

scm_tools_disabled controls whether SCM (Source Control Management) tools are disabled for agents

allowedEditorIds: optional array of string

allowed_editor_ids is the list of editor IDs that are allowed to be used in the organization

allowLocalRunners: optional boolean

allow_local_runners controls whether local runners are allowed to be used in the organization

defaultEditorId: optional string

default_editor_id is the default editor ID to be used when a user doesn’t specify one

defaultEnvironmentImage: optional string

default_environment_image is the default container image when none is defined in repo

deleteArchivedEnvironmentsAfter: optional string

delete_archived_environments_after controls how long archived environments are kept before automatic deletion. 0 means no automatic deletion. Maximum duration is 4 weeks (2419200 seconds).

formatregex

disableFromScratch: optional boolean

disable_from_scratch controls whether non-admin users can create blank environments without a Git or URL initializer.

editorVersionRestrictions: optional map[object { allowedVersions } ]

editor_version_restrictions restricts which editor versions can be used. Maps editor ID to version policy with allowed major versions.

allowedVersions: optional array of string

allowed_versions lists the versions that are allowed If empty, we will use the latest version of the editor

Examples for JetBrains: ["2025.2", "2025.1", "2024.3"]

maximumEnvironmentLifetime: optional string

maximum_environment_lifetime controls for how long environments are allowed to be reused. 0 means no maximum lifetime. Maximum duration is 180 days (15552000 seconds).

formatregex

maximumEnvironmentsPerUser: optional string

maximum_environments_per_user limits total environments (running or stopped) per user

maximumEnvironmentTimeout: optional string

maximum_environment_timeout controls the maximum timeout allowed for environments in seconds. 0 means no limit (never). Minimum duration is 30 minutes (1800 seconds). value must be 0s (no limit) or at least 1800s (30 minutes):

this == duration('0s') || this >= duration('1800s')

formatregex

maximumRunningEnvironmentsPerUser: optional string

maximum_running_environments_per_user limits simultaneously running environments per user

maxPortAdmissionLevel: optional AdmissionLevel

max_port_admission_level caps the maximum admission level a user-opened port may use. UNSPECIFIED means no cap (any AdmissionLevel value is allowed). System ports (VS Code Browser, agents) are exempt. The legacy port_sharing_disabled field, when true, takes precedence and blocks all user-initiated port sharing.

One of the following:

"ADMISSION_LEVEL_UNSPECIFIED"

"ADMISSION_LEVEL_OWNER_ONLY"

"ADMISSION_LEVEL_EVERYONE"

"ADMISSION_LEVEL_ORGANIZATION"

"ADMISSION_LEVEL_CREATOR_ONLY"

membersCreateProjects: optional boolean

members_create_projects controls whether members can create projects

membersRequireProjects: optional boolean

members_require_projects controls whether environments can only be created from projects by non-admin users

portSharingDisabled: optional boolean

port_sharing_disabled controls whether user-initiated port sharing is disabled in the organization. System ports (VS Code Browser, agents) are always exempt from this policy.

projectCreationDefaults: optional object { environmentClasses, insightsEnabled, prebuilds }

project_creation_defaults contains updates to default settings applied to newly created projects.

environmentClasses: optional array of ProjectCreationDefaultEnvironmentClass { environmentClassId, order, prebuild, warmPool }

environment_classes replaces the full list of default environment classes and their per-class settings. Send an empty list to clear defaults.

environmentClassId: optional string

environment_class_id is the ID of the environment class.

formatuuid

order: optional number

order is the priority of this entry (lower = higher priority).

formatint32

prebuild: optional boolean

prebuild controls whether prebuilds are enabled for this environment class on newly created projects.

warmPool: optional ProjectCreationDefaultEnvironmentClassWarmPool { enabled, maxSize, minSize }

warm_pool configures the warm pool for this environment class on newly created projects. Only meaningful when prebuild is true.

enabled: optional boolean

enabled controls whether a warm pool is created for this environment class.

maxSize: optional number

max_size is the maximum number of warm instances. Must be >= min_size and <= 20.

formatint32

maximum20

minSize: optional number

min_size is the minimum number of warm instances. Must be >= 0 and <= max_size.

formatint32

maximum20

insightsEnabled: optional boolean

insights_enabled controls whether Insights (co-author attribution) is automatically enabled on newly created projects.

prebuilds: optional object { disabled, enabled }

prebuilds updates default prebuild settings for newly created projects. When absent, prebuild defaults are left unchanged.

disabled: optional unknown

disabled clears persisted prebuild defaults.

enabled: optional ProjectCreationDefaultsPrebuilds { enableJetbrainsWarmup, prebuildExecutor, timeout, trigger }

enabled sets or updates persisted prebuild defaults.

enableJetbrainsWarmup: optional boolean

enable_jetbrains_warmup controls whether JetBrains IDE warmup runs during prebuilds on newly created projects.

prebuildExecutor: optional Subject { id, principal }

prebuild_executor is the service account used to run prebuilds on newly created projects. Must be a service account (not a user).

id: optional string

id is the UUID of the subject

formatuuid

principal: optional Principal

Principal is the principal of the subject

One of the following:

"PRINCIPAL_UNSPECIFIED"

"PRINCIPAL_ACCOUNT"

"PRINCIPAL_USER"

"PRINCIPAL_RUNNER"

"PRINCIPAL_ENVIRONMENT"

"PRINCIPAL_SERVICE_ACCOUNT"

"PRINCIPAL_RUNNER_MANAGER"

timeout: optional string

timeout is the maximum duration allowed for a prebuild to complete. If not specified, defaults to 1 hour. Must be between 5 minutes and 2 hours.

formatregex

trigger: optional object { dailySchedule }

trigger defines when prebuilds should be created on newly created projects.

dailySchedule: object { hourUtc }

daily_schedule triggers a prebuild once per day at the specified hour (UTC). The actual start time may vary slightly to distribute system load.

hourUtc: optional number

hour_utc is the hour of day (0-23) in UTC when the prebuild should start. The actual start time may be adjusted by a few minutes to balance system load.

formatint32

maximum23

requireCustomDomainAccess: optional boolean

require_custom_domain_access controls whether users must access via custom domain when one is configured. When true, access via app.gitpod.io is blocked.

restrictAccountCreationToScim: optional boolean

restrict_account_creation_to_scim controls whether account creation is restricted to SCIM-provisioned users only. When true and SCIM is configured for the organization, only users provisioned via SCIM can create accounts.

securityAgentPolicy: optional object { crowdstrike }

security_agent_policy contains security agent configuration updates

crowdstrike: optional object { additionalOptions, cidSecretId, enabled, 2 more }

crowdstrike contains CrowdStrike Falcon configuration updates

additionalOptions: optional map[string]

additional_options contains additional FALCONCTL_OPT_* options as key-value pairs

cidSecretId: optional string

cid_secret_id references an organization secret containing the Customer ID (CID)

formatuuid

enabled: optional boolean

enabled controls whether CrowdStrike Falcon is deployed to environments

image: optional string

image is the CrowdStrike Falcon sensor container image reference

tags: optional string

tags are optional tags to apply to the Falcon sensor

vetoExecPolicy: optional VetoExecPolicy { action, enabled, executables }

veto_exec_policy contains the veto exec policy for environments.

action: optional KernelControlsAction

action specifies what action kernel-level controls take on policy violations

One of the following:

"KERNEL_CONTROLS_ACTION_UNSPECIFIED"

"KERNEL_CONTROLS_ACTION_BLOCK"

"KERNEL_CONTROLS_ACTION_AUDIT"

enabled: optional boolean

enabled controls whether executable blocking is active

executables: optional array of string

executables is the list of executable paths or names to block

webBrowserDisabled: optional boolean

web_browser_disabled controls whether users can open the built-in web browser from environment pages. This does not affect VS Code Browser.

UpdateOrganizationPolicies

curl https://app.gitpod.io/api/gitpod.v1.OrganizationService/UpdateOrganizationPolicies \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{
          "organizationId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
        }'

{}

Returns Examples

{}