Organization

An Organization is a top-level resource in WorkOS. Each Connection, Directory, and Audit Trail Event belongs to an Organization. An Organization will usually represent one of your customers. There is no limit to the number of organizations you can create in WorkOS.

Get an Organization

Get the details of an existing organization.

JavaScript

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const organization = await workos.organizations.getOrganization(
  'org_01EHZNVPK3SFK441A1RGBFSHRT',
);

 {
  "object": "organization",
  "id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "name": "Acme Inc.",
  "domains": [
    {
      "object": "organization_domain",
      "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
      "organization_id": "org_01HE8GSH8FQPASKSY27THRKRBP",
      "domain": "foo-corp.com",
      "state": "pending",
      "verification_prefix": "superapp-domain-verification-z3kjny",
      "verification_token": "m5Oztg3jdK4NJLgs8uIlIprMw",
      "verification_strategy": "dns",
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "metadata": {
    "tier": "diamond"
  },
  "external_id": "2fe01467-f7ea-4dd2-8b79-c2b4f56d0191",
  "stripe_customer_id": "cus_R9qWAGMQ6nGE7V",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}

GET

`/organizations/:id`

`Parameters`

`Returns`

Get an Organization by External ID

Get the details of an existing organization by an external identifier.

JavaScript

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const organization = await workos.organizations.getOrganizationByExternalId(
  '2fe01467-f7ea-4dd2-8b79-c2b4f56d0191',
);

 {
  "object": "organization",
  "id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "name": "Acme Inc.",
  "domains": [
    {
      "object": "organization_domain",
      "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
      "organization_id": "org_01HE8GSH8FQPASKSY27THRKRBP",
      "domain": "foo-corp.com",
      "state": "pending",
      "verification_prefix": "superapp-domain-verification-z3kjny",
      "verification_token": "m5Oztg3jdK4NJLgs8uIlIprMw",
      "verification_strategy": "dns",
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "metadata": {
    "tier": "diamond"
  },
  "external_id": "2fe01467-f7ea-4dd2-8b79-c2b4f56d0191",
  "stripe_customer_id": "cus_R9qWAGMQ6nGE7V",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}

GET

`/organizations/external_id/:external_id`

`Parameters`

`Returns`

List Organizations

Get a list of all of your existing organizations matching the criteria specified.

JavaScript

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const organizations = await workos.organizations.listOrganizations({
  domains: ['foo-corp.com'],
});

console.log(organizations.data);

 {
  "object": "list",
  "data": [
    {
      "object": "organization",
      "id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "name": "Acme Inc.",
      "domains": [
        {
          "object": "organization_domain",
          "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
          "organization_id": "org_01HE8GSH8FQPASKSY27THRKRBP",
          "domain": "foo-corp.com",
          "state": "pending",
          "verification_prefix": "superapp-domain-verification-z3kjny",
          "verification_token": "m5Oztg3jdK4NJLgs8uIlIprMw",
          "verification_strategy": "dns",
          "created_at": "2026-01-15T12:00:00.000Z",
          "updated_at": "2026-01-15T12:00:00.000Z"
        }
      ],
      "metadata": {
        "tier": "diamond"
      },
      "external_id": "2fe01467-f7ea-4dd2-8b79-c2b4f56d0191",
      "stripe_customer_id": "cus_R9qWAGMQ6nGE7V",
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "list_metadata": {
    "before": "org_01HXYZ123456789ABCDEFGHIJ",
    "after": "org_01HXYZ987654321KJIHGFEDCBA"
  }
}

GET

`/organizations`

`Parameters`

`Returns` `object`

Create an Organization

Creates a new organization in the current environment.

You can include one or more domains to associate with the organization, but you should verify the ownership of every domain before setting its state to verified.

JavaScript

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const organization = await workos.organizations.createOrganization({
  name: 'Foo Corp',
  domainData: [
    {
      domain: 'foo-corp.com',
      state: 'pending',
    },
  ],
  externalId: '2fe01467-f7ea-4dd2-8b79-c2b4f56d0191',
  metadata: {
    tier: 'diamond',
  },
});

 {
  "object": "organization",
  "name": "Foo Corp",
  "domains": [
    {
      "object": "organization_domain",
      "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
      "organization_id": "org_01HE8GSH8FQPASKSY27THRKRBP",
      "domain": "foo-corp.com",
      "state": "pending",
      "verification_prefix": "superapp-domain-verification-z3kjny",
      "verification_token": "m5Oztg3jdK4NJLgs8uIlIprMw",
      "verification_strategy": "dns",
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "metadata": {
    "tier": "diamond"
  },
  "stripe_customer_id": "cus_R9qWAGMQ6nGE7V",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "allow_profiles_outside_organization": false,
  "id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "external_id": "ext_12345"
}

POST

`/organizations`

`Returns`

Update an Organization

Updates an organization in the current environment.

You can include one or more domains to associate with the organization, but you should verify the ownership of every domain before setting its state to verified.

JavaScript

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const organization = await workos.organizations.updateOrganization({
  organization: 'org_01EHZNVPK3SFK441A1RGBFSHRT',
  name: 'Foo Corp',
  domainData: [
    {
      domain: 'foo-corp.com',
      state: 'verified',
    },
  ],
  externalId: '2fe01467-f7ea-4dd2-8b79-c2b4f56d0191',
  metadata: {
    tier: 'diamond',
  },
  stripeCustomerId: 'cus_R9qWAGMQ6nGE7V',
});

 {
  "object": "organization",
  "name": "Foo Corp",
  "domains": [
    {
      "object": "organization_domain",
      "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
      "organization_id": "org_01HE8GSH8FQPASKSY27THRKRBP",
      "domain": "foo-corp.com",
      "state": "pending",
      "verification_prefix": "superapp-domain-verification-z3kjny",
      "verification_token": "m5Oztg3jdK4NJLgs8uIlIprMw",
      "verification_strategy": "dns",
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "metadata": {
    "tier": "diamond"
  },
  "stripe_customer_id": "cus_R9qWAGMQ6nGE7V",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "allow_profiles_outside_organization": false,
  "id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "external_id": "2fe01467-f7ea-4dd2-8b79-c2b4f56d0191"
}

PUT

`/organizations/:id`

`Parameters`

`Returns`

Delete an Organization

Permanently deletes an organization in the current environment. It cannot be undone.

Request

JavaScript

 curl --request DELETE \
  --url https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT \
  --header "Authorization: Bearer sk_example_123456789"

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.organizations.deleteOrganization('org_01EHZNVPK3SFK441A1RGBFSHRT');

 require "workos"

WorkOS.configure do |config|
  config.key = "sk_example_123456789"
end

WorkOS::Organizations.delete_organization(
  id: "org_01EHZNVPK3SFK441A1RGBFSHRT"
)

 from workos import WorkOSClient

workos_client = WorkOSClient(
    api_key="sk_example_123456789", client_id="client_123456789"
)

workos_client.organizations.delete_organization(
    organization_id="org_01EHZNVPK3SFK441A1RGBFSHRT"
)

 package main

import (
	"context"

	"github.com/workos/workos-go/v3/pkg/organizations"
)

func main() {
	organizations.SetAPIKey("sk_example_123456789")

	err := organizations.DeleteOrganization(
		context.Background(),
		organizations.DeleteOrganizationOpts{
			Organization: "org_01EHZNVPK3SFK441A1RGBFSHRT",
		},
	)

}

 <?php

WorkOS\WorkOS::setApiKey("sk_example_123456789");

$organizations = new WorkOS\Organizations();

$organizations->deleteOrganization("org_01EHZNVPK3SFK441A1RGBFSHRT");

 import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

String organizationId = "org_01EHZNVPK3SFK441A1RGBFSHRT";
workos.organizations.deleteOrganization(organizationId);

 WorkOS.SetApiKey("sk_example_123456789");

var organizationsService = new OrganizationsService();

await organizationsService.DeleteOrganization("org_01EHZNVPK3SFK441A1RGBFSHRT");

DELETE

`/organizations/:id`

`Parameters`

Pipes Continue to the next section

Up next

Organization

Get an Organization

/organizations/:id

Parameters

id: string

Returns

organization: object

Get an Organization by External ID

/organizations/external_id/:external_id

Parameters

external_id: string

Returns

organization: object

List Organizations

/organizations

Parameters

before?: string

after?: string

limit?: integer

order?: "normal" | "desc" | "asc"

domains?: string[]

search?: string

Returns object

object: "list"

data: object[]

list_metadata: object

Create an Organization

/organizations

name: string

allow_profiles_outside_organization?: boolean

domains?: string[]

domain_data?: object[]

metadata?: object

external_id?: string

Returns

organization: object

Update an Organization

/organizations/:id

name?: string

allow_profiles_outside_organization?: boolean

domains?: string[]Deprecated

domain_data?: object[]

stripe_customer_id?: string

metadata?: object

external_id?: string

Parameters

id: string

Returns

organization: object

Delete an Organization

/organizations/:id

Parameters

id: string

`/organizations/:id`

`Parameters`

`Returns`

`/organizations/external_id/:external_id`

`Parameters`

`Returns`

`/organizations`

`Parameters`

`Returns` `object`

`/organizations`

`Returns`

`/organizations/:id`

`Parameters`

`Returns`

`/organizations/:id`

`Parameters`