Organization membership

An organization membership is a top-level resource that represents a user’s relationship with an organization. A user may be a member of zero, one, or many organizations.

See the events reference documentation for the organization membership events.

Get an organization membership

Get the details of an existing organization membership.

JavaScript

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

const workos = new WorkOS('sk_example_123456789');

const organizationMembership =
  await workos.userManagement.getOrganizationMembership(
    'om_01E4ZCR3C56J083X43JQXF3JK5',
  );

 {
  "object": "organization_membership",
  "id": "om_01HXYZ123456789ABCDEFGHIJ",
  "user_id": "user_01EHQTV6MWP9P1F4ZXGXMC8ABB",
  "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "status": "active",
  "directory_managed": false,
  "organization_name": "Acme Corp",
  "custom_attributes": {
    "department": "Engineering",
    "title": "Developer Experience Engineer",
    "location": "Brooklyn"
  },
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "role": {
    "slug": "admin"
  }
}

GET

`/user_management/organization_memberships/:id`

`Parameters`

`Returns`

List organization memberships

Get a list of all organization memberships matching the criteria specified. At least one of user_id or organization_id must be provided. By default only active memberships are returned. Use the statuses parameter to filter by other statuses.

JavaScript

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

const workos = new WorkOS('sk_example_123456789');

const organizationMemberships =
  await workos.userManagement.listOrganizationMemberships({
    userId: 'user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E',
  });

console.log(organizationMemberships.data);

 {
  "object": "list",
  "data": [
    {
      "object": "organization_membership",
      "id": "om_01HXYZ123456789ABCDEFGHIJ",
      "user_id": "user_01EHQTV6MWP9P1F4ZXGXMC8ABB",
      "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
      "status": "active",
      "directory_managed": false,
      "organization_name": "Acme Corp",
      "custom_attributes": {
        "department": "Engineering",
        "title": "Developer Experience Engineer",
        "location": "Brooklyn"
      },
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z",
      "role": {
        "slug": "admin"
      }
    }
  ],
  "list_metadata": {
    "before": "om_01HXYZ123456789ABCDEFGHIJ",
    "after": "om_01HXYZ987654321KJIHGFEDCBA"
  }
}

GET

`/user_management/organization_memberships`

`Parameters`

`Returns` `object`

Create an organization membership

Creates a new active organization membership for the given organization and user.

Calling this API with an organization and user that match an inactive organization membership will activate the membership with the specified role(s).

JavaScript

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

const workos = new WorkOS('sk_example_123456789');

const organizationMembership =
  await workos.userManagement.createOrganizationMembership({
    organizationId: 'org_01E4ZCR3C56J083X43JQXF3JK5',
    userId: 'user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E',
    roleSlug: 'admin',
  });

 {
  "object": "organization_membership",
  "id": "om_01HXYZ123456789ABCDEFGHIJ",
  "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
  "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5",
  "status": "active",
  "directory_managed": false,
  "organization_name": "Acme Corp",
  "custom_attributes": {
    "department": "Engineering",
    "title": "Developer Experience Engineer",
    "location": "Brooklyn"
  },
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "role": {
    "slug": "admin"
  }
}

POST

`/user_management/organization_memberships`

`Returns`

Update an organization membership

Update the details of an existing organization membership.

JavaScript

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

const workos = new WorkOS('sk_example_123456789');

const organizationMembership =
  await workos.userManagement.updateOrganizationMembership(
    'om_01E4ZCR3C56J083X43JQXF3JK5',
    {
      roleSlug: 'admin',
    },
  );

 {
  "object": "organization_membership",
  "id": "om_01HXYZ123456789ABCDEFGHIJ",
  "user_id": "user_01EHQTV6MWP9P1F4ZXGXMC8ABB",
  "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "status": "active",
  "directory_managed": false,
  "organization_name": "Acme Corp",
  "custom_attributes": {
    "department": "Engineering",
    "title": "Developer Experience Engineer",
    "location": "Brooklyn"
  },
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "role": {
    "slug": "admin"
  }
}

PUT

`/user_management/organization_memberships/:id`

`Parameters`

`Returns`

Delete an organization membership

Permanently deletes an existing organization membership. It cannot be undone.

Request

JavaScript

 curl --request DELETE \
  --url https://api.workos.com/user_management/organization_memberships/om_01E4ZCR3C56J083X43JQXF3JK5 \
  --header "Authorization: Bearer sk_example_123456789"

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

const workos = new WorkOS('sk_example_123456789');

await workos.userManagement.deleteOrganizationMembership(
  'om_01E4ZCR3C56J083X43JQXF3JK5',
);

 require "workos"

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

UserManagement.delete_organization_membership(
  id: "om_01E4ZCR3C56J083X43JQXF3JK5"
)

 from workos import WorkOSClient

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

workos_client.user_management.delete_organization_membership(
    organization_membership_id="om_01E4ZCR3C56J083X43JQXF3JK5"
)

 package main

import (
	"context"

	"github.com/workos/workos-go/v2/pkg/usermanagement"
)

func main() {
	usermanagement.SetAPIKey(
		"sk_example_123456789",
	)

	usermanagement.DeleteOrganizationMembership(
		context.Background(),
		usermanagement.DeleteOrganizationMembershipOpts{
			OrganizationMembership: "om_01E4ZCR3C56J083X43JQXF3JK5",
		},
	)
}

 <?php

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

$userManagement = new WorkOS\UserManagement();

$userManagement->deleteOrganizationMembership("om_01E4ZCR3C56J083X43JQXF3JK5");

 import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.userManagement.deleteOrganizationMembership("om_01E4ZCR3C56J083X43JQXF3JK5");

DELETE

`/user_management/organization_memberships/:id`

`Parameters`

Deactivate an organization membership

Deactivates an active organization membership. Emits an organization_membership.updated event upon successful deactivation.

Deactivating an inactive membership is a no-op and does not emit an event.
Deactivating a pending membership returns an error. This membership should be deleted instead.

See the membership management documentation for additional details.

JavaScript

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

const workos = new WorkOS('sk_example_123456789');

const organizationMembership =
  await workos.userManagement.deactivateOrganizationMembership(
    'om_01E4ZCR3C56J083X43JQXF3JK5',
  );

 {
  "object": "organization_membership",
  "id": "om_01HXYZ123456789ABCDEFGHIJ",
  "user_id": "user_01EHQTV6MWP9P1F4ZXGXMC8ABB",
  "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "status": "inactive",
  "directory_managed": false,
  "organization_name": "Acme Corp",
  "custom_attributes": {
    "department": "Engineering",
    "title": "Developer Experience Engineer",
    "location": "Brooklyn"
  },
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "role": {
    "slug": "admin"
  }
}

PUT

`/user_management/organization_memberships/:id/deactivate`

`Parameters`

`Returns`

Reactivate an organization membership

Reactivates an inactive organization membership, retaining the pre-existing role(s). Emits an organization_membership.updated event upon successful reactivation.

Reactivating an active membership is a no-op and does not emit an event.
Reactivating a pending membership returns an error. The user needs to accept the invitation instead.

See the membership management documentation for additional details.

JavaScript

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

const workos = new WorkOS('sk_example_123456789');

const organizationMembership =
  await workos.userManagement.reactivateOrganizationMembership(
    'om_01E4ZCR3C56J083X43JQXF3JK5',
  );

 {
  "object": "organization_membership",
  "id": "om_01HXYZ123456789ABCDEFGHIJ",
  "user_id": "user_01EHQTV6MWP9P1F4ZXGXMC8ABB",
  "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "status": "active",
  "directory_managed": false,
  "organization_name": "Acme Corp",
  "custom_attributes": {
    "department": "Engineering",
    "title": "Developer Experience Engineer",
    "location": "Brooklyn"
  },
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "role": {
    "slug": "admin"
  }
}

PUT

`/user_management/organization_memberships/:id/reactivate`

`Parameters`

`Returns`

List groups

Get a list of groups that an organization membership belongs to.

cURL

 curl "https://api.workos.com/user_management/organization_memberships/om_01HXYZ123456789ABCDEFGHIJ/groups" \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "object": "list",
  "data": [
    {
      "object": "group",
      "id": "group_01HXYZ123456789ABCDEFGHIJ",
      "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "name": "Engineering",
      "description": "The engineering team",
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "list_metadata": {
    "before": "group_01HXYZ123456789ABCDEFGHIJ",
    "after": "group_01HXYZ987654321KJIHGFEDCBA"
  }
}

Feature flagged

GET

`/user_management/organization_memberships/:omId/groups`

`Parameters`

`Returns` `object`

Invitation Continue to the next section

Up next

Organization membership

Get an organization membership

/user_management/organization_memberships/:id

Parameters

id: string

Returns

organization_membership: object

List organization memberships

/user_management/organization_memberships

Parameters

before?: string

after?: string

limit?: integer

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

organization_id?: string

statuses?: ("active" | "inactive" | "pending")[]

user_id?: string

Returns object

object: "list"

data: object[]

list_metadata: object

Create an organization membership

/user_management/organization_memberships

user_id: string

organization_id: string

role_slug?: string

role_slugs?: string[]

Returns

organization_membership: object

Update an organization membership

/user_management/organization_memberships/:id

role_slug?: string

role_slugs?: string[]

Parameters

id: string

Returns

organization_membership: object

Delete an organization membership

/user_management/organization_memberships/:id

Parameters

id: string

Deactivate an organization membership

/user_management/organization_memberships/:id/deactivate

Parameters

id: string

Returns

organization_membership: object

Reactivate an organization membership

/user_management/organization_memberships/:id/reactivate

Parameters

id: string

Returns

organization_membership: object

List groups

/user_management/organization_memberships/:omId/groups

Parameters

omId: string

before?: string

after?: string

limit?: integer

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

Returns object

object: "list"

data: object[]

list_metadata: object

`/user_management/organization_memberships/:id`

`Parameters`

`Returns`

`/user_management/organization_memberships`

`Parameters`

`Returns` `object`

`/user_management/organization_memberships`

`Returns`

`/user_management/organization_memberships/:id`

`Parameters`

`Returns`

`/user_management/organization_memberships/:id`

`Parameters`

`/user_management/organization_memberships/:id/deactivate`

`Parameters`

`Returns`

`/user_management/organization_memberships/:id/reactivate`

`Parameters`

`Returns`

`/user_management/organization_memberships/:omId/groups`

`Parameters`

`Returns` `object`