Gitpod API Reference | Organizations

Organizations

organizations

Methods

Create Organization -> { organization, member }

post/gitpod.v1.OrganizationService/CreateOrganization

Creates a new organization with the specified name and settings.

Use this method to:

Create a new organization for team collaboration
Set up automatic domain-based invites for team members
Join the organization immediately upon creation

Examples

Create a basic organization:

Creates an organization with just a name.
```
name: "Acme Corp Engineering"
joinOrganization: true
```
Create with domain-based invites:

Creates an organization that automatically invites users with matching email domains.
```
name: "Acme Corp"
joinOrganization: true
inviteAccountsWithMatchingDomain: true
```

Delete Organization -> unknown

post/gitpod.v1.OrganizationService/DeleteOrganization

Permanently deletes an organization.

Use this method to:

Remove unused organizations
Clean up test organizations
Complete organization migration

Examples

Delete organization:

Permanently removes an organization and all its data.
```
organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
```

Join Organization -> { member }

post/gitpod.v1.OrganizationService/JoinOrganization

Allows users to join an organization through direct ID, invite link, or domain-based auto-join.

Use this method to:

Join an organization via direct ID or invite
Join automatically based on email domain
Accept organization invitations

Examples

Join via organization ID:

Joins an organization directly when you have the ID.
```
organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
```
Join via invite:

Accepts an organization invitation link.
```
inviteId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
```

Leave Organization -> unknown

post/gitpod.v1.OrganizationService/LeaveOrganization

Removes a user from an organization while preserving organization data.

Use this method to:

Remove yourself from an organization
Clean up inactive memberships
Transfer project ownership before leaving
Manage team transitions

Examples

Leave organization:

Removes user from organization membership.
```
userId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
```

Note: Ensure all projects and resources are transferred before leaving.

List Organizations -> OrganizationsPage<

Organization

post/gitpod.v1.OrganizationService/ListOrganizations

Lists all organizations the caller has access to with optional filtering.

Use this method to:

View organizations you're a member of
Browse all available organizations
Paginate through organization results

Examples

List member organizations:

Shows organizations where the caller is a member.
```
pagination:
  pageSize: 20
scope: SCOPE_MEMBER
```
List all organizations:

Shows all organizations visible to the caller.
```
pagination:
  pageSize: 50
scope: SCOPE_ALL
```

query Parameters

token: string

Optional

pageSize: number

Optional

(maximum: 100, minimum: 0, default: 25)

Response fields

organizations: Array<

Organization

organizations are the organizations that matched the query

pagination: { nextToken }

pagination contains the pagination options for listing organizations

Request example

curl https://app.gitpod.io/api/gitpod.v1.OrganizationService/ListOrganizations \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'

200Example

{
  "organizations": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "name": "name",
      "updatedAt": "2019-12-27T18:11:19.117Z",
      "inviteDomains": {
        "domains": [
          "sfN2.l.iJR-BU.u9JV9.a.m.o2D-4b-Jd.0Z-kX.L.n.S.f.UKbxB"
        ]
      }
    }
  ],
  "pagination": {
    "nextToken": "nextToken"
  }
}

List Members -> MembersPage<

OrganizationMember

post/gitpod.v1.OrganizationService/ListMembers

Lists and filters organization members with optional pagination.

Use this method to:

View all organization members
Monitor member activity
Manage team membership

Examples

List active members:

Retrieves active members with pagination.

organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
pagination:
  pageSize: 20

List with pagination:

Retrieves next page of members.

organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
pagination:
  pageSize: 50
  token: "next-page-token-from-previous-response"

Get Organization -> { organization }

post/gitpod.v1.OrganizationService/GetOrganization

Gets details about a specific organization.

Use this method to:

Retrieve organization settings and configuration
Check organization membership status
View domain verification settings

Examples

Get organization details:

Retrieves information about a specific organization.
```
organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
```

Set Role -> unknown

post/gitpod.v1.OrganizationService/SetRole

Manages organization membership and roles by setting a user's role within the organization.

Use this method to:

Promote members to admin role
Change member permissions
Demote admins to regular members

Examples

Promote to admin:

Makes a user an organization administrator.

organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
userId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
role: ORGANIZATION_ROLE_ADMIN

Change to member:

Changes a user's role to regular member.

organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
userId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
role: ORGANIZATION_ROLE_MEMBER

Update Organization -> { organization }

post/gitpod.v1.OrganizationService/UpdateOrganization

Updates an organization's settings including name, invite domains, and member policies.

Use this method to:

Modify organization display name
Configure email domain restrictions
Update organization-wide settings
Manage member access policies

Examples

Update basic settings:

Changes organization name and invite domains.

organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
name: "New Company Name"
inviteDomains:
  domains:
    - "company.com"
    - "subsidiary.com"

Remove domain restrictions:

Clears all domain-based invite restrictions.

organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
inviteDomains:
  domains: []

Domain types

InviteDomains = { domains }

Organization = { id, createdAt, name, 2 more... }

OrganizationMember = { email, fullName, loginProvider, 5 more... }

Scope = "SCOPE_UNSPECIFIED" | "SCOPE_MEMBER" | "SCOPE_ALL"

Organizations

Domain Verifications

organizations.domain_verifications

Methods

Create Domain Verification -> { domainVerification }

post/gitpod.v1.OrganizationService/CreateDomainVerification

Initiates domain verification process to enable organization features.

Use this method to:

Start domain ownership verification
Enable automatic team joining
Set up SSO restrictions
Configure email-based policies

Examples

Verify primary domain:

Starts verification for main company domain.

organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
domain: "acme-corp.com"

Verify subsidiary domain:

Adds verification for additional company domain.

organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
domain: "acme-subsidiary.com"

Delete Domain Verification -> unknown

post/gitpod.v1.OrganizationService/DeleteDomainVerification

Removes a domain verification request.

Use this method to:

Cancel pending verifications
Remove verified domains
Clean up unused domain records

Examples

Delete verification:

Removes a domain verification request.

domainVerificationId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"

List Domain Verifications -> DomainVerificationsPage<

DomainVerification

post/gitpod.v1.OrganizationService/ListDomainVerifications

Lists and monitors domain verification status across an organization.

Use this method to:

Track verification progress
View all verified domains
Monitor pending verifications
Audit domain settings

Examples

List all verifications:

Shows all domain verifications regardless of status.

organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
pagination:
  pageSize: 20

List with pagination:

Retrieves next page of verifications.

organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
pagination:
  pageSize: 20
  token: "next-page-token-from-previous-response"

Get Domain Verification -> { domainVerification }

post/gitpod.v1.OrganizationService/GetDomainVerification

Retrieves the status of a domain verification request.

Use this method to:

Check verification progress
View verification requirements
Monitor domain status

Examples

Get verification status:

Checks the current state of a domain verification.
```
domainVerificationId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
```

Verify Domain -> { domainVerification }

post/gitpod.v1.OrganizationService/VerifyDomain

Verifies domain ownership for an organization.

Use this method to:

Complete domain verification process
Enable domain-based features
Validate DNS configuration

Examples

Verify domain ownership:

Verifies ownership after DNS records are configured.
```
domainVerificationId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
```

Domain types

DomainVerification = { id, domain, organizationId, 4 more... }

DomainVerificationState = "DOMAIN_VERIFICATION_STATE_UNSPECIFIED" | "DOMAIN_VERIFICATION_STATE_PENDING" | "DOMAIN_VERIFICATION_STATE_VERIFIED"

Organizations

Invites

organizations.invites

Methods

Create Organization Invite -> { invite }

post/gitpod.v1.OrganizationService/CreateOrganizationInvite

Creates an invite link for joining an organization. Any existing OrganizationInvites are invalidated and can no longer be used.

Use this method to:

Generate shareable invite links
Manage team growth
Control organization access

Examples

Create organization invite:

Generates a new invite link for the organization.
```
organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
```

Get Organization Invite Summary -> { organizationId, organizationMemberCount, organizationName }

post/gitpod.v1.OrganizationService/GetOrganizationInviteSummary

Retrieves organization details and membership info based on an invite link.

Use this method to:

Preview organization details before joining
Validate invite link authenticity
Check organization size and activity
View team information before accepting

Examples

Get invite summary:

Retrieves organization information from an invite.
```
inviteId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
```

Get Organization Invite -> { invite }

post/gitpod.v1.OrganizationService/GetOrganizationInvite

GetOrganizationInvite

Domain types

OrganizationInvite = { inviteId }

Organizations

SSO Configurations

organizations.sso_configurations

Methods

Create SSO Configuration -> { ssoConfiguration }

post/gitpod.v1.OrganizationService/CreateSSOConfiguration

Creates or updates SSO configuration for organizational authentication.

Use this method to:

Configure OIDC-based SSO providers
Set up built-in providers (Google, GitHub, etc.)
Define custom identity providers
Manage authentication policies

Examples

Configure built-in Google SSO:

Sets up SSO using Google Workspace.

organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
clientId: "012345678-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com"
clientSecret: "GOCSPX-abcdefghijklmnopqrstuvwxyz123456"
issuerUrl: "https://accounts.google.com"
emailDomain: "acme-corp.com"

Configure custom OIDC provider:

Sets up SSO with a custom identity provider.

organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
clientId: "acme-corp-gitpod"
clientSecret: "secret-token-value"
issuerUrl: "https://sso.acme-corp.com"
emailDomain: "acme-corp.com"

Delete SSO Configuration -> unknown

post/gitpod.v1.OrganizationService/DeleteSSOConfiguration

Removes an SSO configuration from an organization.

Use this method to:

Disable SSO authentication
Remove outdated providers
Clean up unused configurations

Examples

Delete SSO configuration:

Removes a specific SSO configuration.
```
ssoConfigurationId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
```

List SSO Configurations -> SSOConfigurationsPage<

SSOConfiguration

post/gitpod.v1.OrganizationService/ListSSOConfigurations

Lists and filters SSO configurations for an organization.

Use this method to:

View all SSO providers
Monitor authentication status
Audit security settings
Manage provider configurations

Examples

List active configurations:

Shows all active SSO providers.

organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
pagination:
  pageSize: 20

List by provider type:

Shows custom SSO configurations.

organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
pagination:
  pageSize: 20
  token: "next-page-token-from-previous-response"

Get SSO Configuration -> { ssoConfiguration }

post/gitpod.v1.OrganizationService/GetSSOConfiguration

Retrieves a specific SSO configuration.

Use this method to:

View SSO provider details
Check configuration status
Verify SSO settings

Examples

Get SSO configuration:

Retrieves details of a specific SSO configuration.
```
ssoConfigurationId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
```

Update SSO Configuration -> unknown

post/gitpod.v1.OrganizationService/UpdateSSOConfiguration

Updates SSO provider settings and authentication rules.

Use this method to:

Rotate client credentials
Update provider endpoints
Modify claim mappings
Change authentication policies
Toggle SSO enforcement

Examples

Update credentials:

Rotates client ID and secret.

ssoConfigurationId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
clientId: "new-client-id"
clientSecret: "new-client-secret"

Update provider status:

Activates or deactivates SSO provider.

ssoConfigurationId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
state: SSO_CONFIGURATION_STATE_ACTIVE

Domain types

ProviderType = "PROVIDER_TYPE_UNSPECIFIED" | "PROVIDER_TYPE_BUILTIN" | "PROVIDER_TYPE_CUSTOM"

SSOConfiguration = { id, issuerUrl, organizationId, 5 more... }

SSOConfigurationState = "SSO_CONFIGURATION_STATE_UNSPECIFIED" | "SSO_CONFIGURATION_STATE_INACTIVE" | "SSO_CONFIGURATION_STATE_ACTIVE"