API Reference

Organizations

Policies

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

GetOrganizationPolicies

organizations.policies.retrieve(PolicyRetrieveParams**kwargs) -> PolicyRetrieveResponse

POST/gitpod.v1.OrganizationService/GetOrganizationPolicies

Gets organization policy settings by organization ID.

Use this method to:

• Retrieve current policy settings for an organization
• View resource limits and restrictions
• Check allowed editors and other configurations

Examples

• Get organization policies:

  Retrieves policy settings for a specific organization.

  organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"

ParametersExpand Collapse

organization_id: str

organization_id is the ID of the organization to retrieve policies for

formatuuid

ReturnsExpand Collapse

class PolicyRetrieveResponse: …

policies: OrganizationPolicies

agent_policy: AgentPolicy

agent_policy contains agent-specific policy settings

command_deny_list: List[str]

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

mcp_disabled: bool

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

scm_tools_disabled: bool

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

conversation_sharing_policy: 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"

max_subagents_per_environment: Optional[int]

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

scm_tools_allowed_group_id: Optional[str]

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

allowed_editor_ids: List[str]

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

allow_local_runners: bool

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

default_editor_id: str

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

default_environment_image: str

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

disable_from_scratch: bool

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

maximum_environments_per_user: str

maximum_environments_per_user limits total environments (running or stopped) per user

maximum_running_environments_per_user: str

maximum_running_environments_per_user limits simultaneously running environments per user

members_create_projects: bool

members_create_projects controls whether members can create projects

members_require_projects: bool

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

organization_id: str

organization_id is the ID of the organization

formatuuid

port_sharing_disabled: bool

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.

require_custom_domain_access: bool

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.

restrict_account_creation_to_scim: bool

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.

web_browser_disabled: bool

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

delete_archived_environments_after: Optional[str]

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

editor_version_restrictions: Optional[Dict[str, EditorVersionRestrictions]]

editor_version_restrictions restricts which editor versions can be used. Maps editor ID to version policy, editor_version_restrictions not set means no restrictions. If empty or not set for an editor, we will use the latest version of the editor

allowed_versions: Optional[List[str]]

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"]

maximum_environment_lifetime: Optional[str]

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

maximum_environment_timeout: Optional[str]

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

project_creation_defaults: Optional[ProjectCreationDefaults]

project_creation_defaults contains default settings applied to newly created projects.

environment_classes: Optional[List[ProjectCreationDefaultEnvironmentClass]]

environment_classes specifies default environment classes and their per-class settings (order, prebuild, warm pool) for newly created projects. Each entry must reference an existing, enabled, non-local-runner environment class in the organization.

environment_class_id: Optional[str]

environment_class_id is the ID of the environment class.

formatuuid

order: Optional[int]

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

formatint32

prebuild: Optional[bool]

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

warm_pool: Optional[ProjectCreationDefaultEnvironmentClassWarmPool]

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

enabled: Optional[bool]

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

max_size: Optional[int]

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

formatint32

maximum20

min_size: Optional[int]

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

formatint32

maximum20

insights_enabled: Optional[bool]

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

prebuilds: Optional[ProjectCreationDefaultsPrebuilds]

prebuilds configures default prebuild settings for newly created projects. When set, prebuilds can be enabled per environment class via the environment_classes entries. When absent, prebuilds are not enabled by default.

enable_jetbrains_warmup: Optional[bool]

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

prebuild_executor: Optional[Subject]

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

id: Optional[str]

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[str]

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[Trigger]

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

daily_schedule: TriggerDailySchedule

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

hour_utc: Optional[int]

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

security_agent_policy: Optional[SecurityAgentPolicy]

security_agent_policy contains security agent configuration for the organization. When configured, security agents are automatically deployed to all environments.

crowdstrike: Optional[CrowdStrikeConfig]

crowdstrike contains CrowdStrike Falcon configuration

additional_options: Optional[Dict[str, str]]

additional_options contains additional FALCONCTL_OPT_* options as key-value pairs. Keys should NOT include the FALCONCTL_OPT_ prefix.

cid_secret_id: Optional[str]

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

formatuuid

enabled: Optional[bool]

enabled controls whether CrowdStrike Falcon is deployed to environments

image: Optional[str]

image is the CrowdStrike Falcon sensor container image reference

tags: Optional[str]

tags are optional tags to apply to the Falcon sensor (comma-separated)

veto_exec_policy: Optional[VetoExecPolicy]

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[bool]

enabled controls whether executable blocking is active

executables: Optional[List[str]]

executables is the list of executable paths or names to block

GetOrganizationPolicies

Python

HTTP

TypeScript

Python

Go

import os
from gitpod import Gitpod

client = Gitpod(
    bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
)
policy = client.organizations.policies.retrieve(
    organization_id="b0e12f6c-4c67-429d-a4a6-d9838b5da047",
)
print(policy.policies)

200 example

{
  "policies": {
    "agentPolicy": {
      "commandDenyList": [
        "string"
      ],
      "mcpDisabled": true,
      "scmToolsDisabled": true,
      "conversationSharingPolicy": "CONVERSATION_SHARING_POLICY_UNSPECIFIED",
      "maxSubagentsPerEnvironment": 10,
      "scmToolsAllowedGroupId": "scmToolsAllowedGroupId"
    },
    "allowedEditorIds": [
      "string"
    ],
    "allowLocalRunners": true,
    "defaultEditorId": "defaultEditorId",
    "defaultEnvironmentImage": "defaultEnvironmentImage",
    "disableFromScratch": true,
    "maximumEnvironmentsPerUser": "maximumEnvironmentsPerUser",
    "maximumRunningEnvironmentsPerUser": "maximumRunningEnvironmentsPerUser",
    "membersCreateProjects": true,
    "membersRequireProjects": true,
    "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "portSharingDisabled": true,
    "requireCustomDomainAccess": true,
    "restrictAccountCreationToScim": true,
    "webBrowserDisabled": true,
    "deleteArchivedEnvironmentsAfter": "+9125115.360s",
    "editorVersionRestrictions": {
      "foo": {
        "allowedVersions": [
          "string"
        ]
      }
    },
    "maximumEnvironmentLifetime": "+9125115.360s",
    "maximumEnvironmentLifetimeStrict": true,
    "maximumEnvironmentTimeout": "+9125115.360s",
    "maxPortAdmissionLevel": "ADMISSION_LEVEL_UNSPECIFIED",
    "projectCreationDefaults": {
      "environmentClasses": [
        {
          "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "order": 0,
          "prebuild": true,
          "warmPool": {
            "enabled": true,
            "maxSize": 20,
            "minSize": 20
          }
        }
      ],
      "insightsEnabled": true,
      "prebuilds": {
        "enableJetbrainsWarmup": true,
        "prebuildExecutor": {
          "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "principal": "PRINCIPAL_UNSPECIFIED"
        },
        "timeout": "+9125115.360s",
        "trigger": {
          "dailySchedule": {
            "hourUtc": 23
          }
        }
      }
    },
    "securityAgentPolicy": {
      "crowdstrike": {
        "additionalOptions": {
          "foo": "string"
        },
        "cidSecretId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "enabled": true,
        "image": "image",
        "tags": "tags"
      },
      "customAgents": [
        {
          "id": "id",
          "description": "description",
          "enabled": true,
          "envMappings": [
            {
              "name": "name",
              "secretName": "secretName"
            }
          ],
          "name": "name",
          "startCommand": "startCommand"
        }
      ]
    },
    "vetoExecPolicy": {
      "action": "KERNEL_CONTROLS_ACTION_UNSPECIFIED",
      "enabled": true,
      "executables": [
        "string"
      ],
      "safelist": [
        "string"
      ]
    },
    "vetoFilePolicy": {
      "blockDevices": {
        "action": "KERNEL_CONTROLS_ACTION_UNSPECIFIED",
        "enabled": true
      },
      "enabled": true,
      "paths": {
        "defaultEffect": "KERNEL_CONTROLS_ACTION_UNSPECIFIED",
        "defaultSurface": "VETO_FILE_SURFACE_UNSPECIFIED",
        "entries": [
          {
            "effect": "KERNEL_CONTROLS_ACTION_UNSPECIFIED",
            "path": "path",
            "surface": "VETO_FILE_SURFACE_UNSPECIFIED",
            "trackChanges": true
          }
        ]
      }
    }
  }
}

Returns Examples

200 example

{
  "policies": {
    "agentPolicy": {
      "commandDenyList": [
        "string"
      ],
      "mcpDisabled": true,
      "scmToolsDisabled": true,
      "conversationSharingPolicy": "CONVERSATION_SHARING_POLICY_UNSPECIFIED",
      "maxSubagentsPerEnvironment": 10,
      "scmToolsAllowedGroupId": "scmToolsAllowedGroupId"
    },
    "allowedEditorIds": [
      "string"
    ],
    "allowLocalRunners": true,
    "defaultEditorId": "defaultEditorId",
    "defaultEnvironmentImage": "defaultEnvironmentImage",
    "disableFromScratch": true,
    "maximumEnvironmentsPerUser": "maximumEnvironmentsPerUser",
    "maximumRunningEnvironmentsPerUser": "maximumRunningEnvironmentsPerUser",
    "membersCreateProjects": true,
    "membersRequireProjects": true,
    "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "portSharingDisabled": true,
    "requireCustomDomainAccess": true,
    "restrictAccountCreationToScim": true,
    "webBrowserDisabled": true,
    "deleteArchivedEnvironmentsAfter": "+9125115.360s",
    "editorVersionRestrictions": {
      "foo": {
        "allowedVersions": [
          "string"
        ]
      }
    },
    "maximumEnvironmentLifetime": "+9125115.360s",
    "maximumEnvironmentLifetimeStrict": true,
    "maximumEnvironmentTimeout": "+9125115.360s",
    "maxPortAdmissionLevel": "ADMISSION_LEVEL_UNSPECIFIED",
    "projectCreationDefaults": {
      "environmentClasses": [
        {
          "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "order": 0,
          "prebuild": true,
          "warmPool": {
            "enabled": true,
            "maxSize": 20,
            "minSize": 20
          }
        }
      ],
      "insightsEnabled": true,
      "prebuilds": {
        "enableJetbrainsWarmup": true,
        "prebuildExecutor": {
          "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "principal": "PRINCIPAL_UNSPECIFIED"
        },
        "timeout": "+9125115.360s",
        "trigger": {
          "dailySchedule": {
            "hourUtc": 23
          }
        }
      }
    },
    "securityAgentPolicy": {
      "crowdstrike": {
        "additionalOptions": {
          "foo": "string"
        },
        "cidSecretId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "enabled": true,
        "image": "image",
        "tags": "tags"
      },
      "customAgents": [
        {
          "id": "id",
          "description": "description",
          "enabled": true,
          "envMappings": [
            {
              "name": "name",
              "secretName": "secretName"
            }
          ],
          "name": "name",
          "startCommand": "startCommand"
        }
      ]
    },
    "vetoExecPolicy": {
      "action": "KERNEL_CONTROLS_ACTION_UNSPECIFIED",
      "enabled": true,
      "executables": [
        "string"
      ],
      "safelist": [
        "string"
      ]
    },
    "vetoFilePolicy": {
      "blockDevices": {
        "action": "KERNEL_CONTROLS_ACTION_UNSPECIFIED",
        "enabled": true
      },
      "enabled": true,
      "paths": {
        "defaultEffect": "KERNEL_CONTROLS_ACTION_UNSPECIFIED",
        "defaultSurface": "VETO_FILE_SURFACE_UNSPECIFIED",
        "entries": [
          {
            "effect": "KERNEL_CONTROLS_ACTION_UNSPECIFIED",
            "path": "path",
            "surface": "VETO_FILE_SURFACE_UNSPECIFIED",
            "trackChanges": true
          }
        ]
      }
    }
  }
}