<!-- llms.txt: https://workos.com/llms.txt -->

# Organizations

List the organizations a user belongs to and manage the membership of the organization the token was issued for, including invitations and each member's roles.

## Invite a user

Invite a user to the organization the token was issued for, assigning a role and sending the invitation email.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation InviteUser($input: InviteUserInput!) {
  inviteUser(input: $input) {
    __typename
    ... on InvalidInviteeEmail {
      email
    }
    ... on InvalidInviteeRole {
      roleSlug
    }
    ... on InviteeAlreadyInvited {
      email
    }
    ... on InviteeAlreadyMember {
      email
    }
    ... on InviteeEmailNotDeliverable {
      email
    }
    ... on UserInvited {
      invitation {
        createdAt
        email
        expiresAt
        id
        roleSlug
        status
      }
    }
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "inviteUser": {
      "__typename": "InvalidInvitationExpiry"
    }
  }
}
```

:::

## List organization members

List members of the organization the token was issued for, with their roles.

:::code-group

```graphql language="graphql" title="Query" tab="1"
query OrganizationMemberships($after: String, $before: String, $limit: Int, $order: PaginationOrder, $roleSlug: String, $search: String) {
  organizationMemberships(after: $after, before: $before, limit: $limit, order: $order, roleSlug: $roleSlug, search: $search) {
    data {
      createdAt
      email
      emailVerified
      firstName
      id
      lastActivityAt
      lastName
      profilePictureUrl
      roles {
        name
        slug
      }
      status
    }
    listMetadata {
      after
      before
    }
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "organizationMemberships": {
      "data": [
        {
          "createdAt": "2024-01-01T00:00:00.000Z",
          "email": "email_example",
          "emailVerified": true,
          "firstName": "firstName_example",
          "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
          "lastActivityAt": "2024-01-01T00:00:00.000Z",
          "lastName": "lastName_example",
          "profilePictureUrl": "profilePictureUrl_example",
          "roles": [
            {
              "name": "name_example",
              "slug": "slug_example"
            }
          ],
          "status": "Active"
        }
      ],
      "listMetadata": {
        "after": "after_example",
        "before": "before_example"
      }
    }
  }
}
```

:::

## Get an organization

Returns an organization by ID within the token's environment.

:::code-group

```graphql language="graphql" title="Query" tab="1"
query Organization($id: ID!) {
  organization(id: $id) {
    allowProfilesOutsideOrganization
    createdAt
    id
    name
    updatedAt
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "organization": {
      "allowProfilesOutsideOrganization": true,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "name": "name_example",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}
```

:::

## List a user's organizations

List organizations the authenticated user belongs to.

:::code-group

```graphql language="graphql" title="Query" tab="1"
query Organizations {
  organizations {
    id
    isCurrent
    name
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "organizations": [
      {
        "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
        "isCurrent": true,
        "name": "name_example"
      }
    ]
  }
}
```

:::

## Remove a member

Remove a member from the organization the token was issued for.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation RemoveMember($input: RemoveMemberInput!) {
  removeMember(input: $input) {
    __typename
    ... on MemberIsManagedByDirectory {
      userId
    }
    ... on MemberNotFound {
      userId
    }
    ... on MemberRemoved {
      userId
    }
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "removeMember": {
      "__typename": "MemberIsManagedByDirectory",
      "userId": "userId_01EHWNCE74X7JSDV0X3SZ3KJNY"
    }
  }
}
```

:::

## Resend an invitation

Resend a pending, expired, or revoked invitation for the organization the token was issued for. If the original invitation has expired or been revoked, a new invitation is created with the same role.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation ResendInvitation($input: ResendInvitationInput!) {
  resendInvitation(input: $input) {
    __typename
    ... on InvitationResent {
      invitation {
        createdAt
        email
        expiresAt
        id
        roleSlug
        status
      }
    }
    ... on InviteeAlreadyAccepted {
      userId
    }
    ... on InviteeEmailNotDeliverable {
      email
    }
    ... on ResendInvitationNotFound {
      userId
    }
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "resendInvitation": {
      "__typename": "InvitationResent",
      "invitation": {
        "createdAt": "2024-01-01T00:00:00.000Z",
        "email": "email_example",
        "expiresAt": "2024-01-01T00:00:00.000Z",
        "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
        "roleSlug": "roleSlug_example",
        "status": "Accepted"
      }
    }
  }
}
```

:::

## Revoke an invitation

Revoke a pending invitation for the organization the token was issued for.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation RevokeInvitation($input: RevokeInvitationInput!) {
  revokeInvitation(input: $input) {
    __typename
    ... on InvitationNotFound {
      userId
    }
    ... on InvitationNotPending {
      userId
    }
    ... on InvitationRevoked {
      invitation {
        createdAt
        email
        expiresAt
        id
        roleSlug
        status
      }
    }
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "revokeInvitation": {
      "__typename": "InvitationNotFound",
      "userId": "userId_01EHWNCE74X7JSDV0X3SZ3KJNY"
    }
  }
}
```

:::

## Update a member's role

Update an organization member's roles within the organization the token was issued for. When multiple roles are enabled, all provided role slugs are assigned; otherwise only the first is used.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation UpdateMemberRole($input: UpdateMemberRoleInput!) {
  updateMemberRole(input: $input) {
    __typename
    ... on MemberNotFound {
      userId
    }
    ... on MemberRoleUpdated {
      member {
        createdAt
        email
        emailVerified
        firstName
        id
        lastActivityAt
        lastName
        profilePictureUrl
        status
      }
    }
    ... on RoleNotFound {
      roleSlugs
    }
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "updateMemberRole": {
      "__typename": "MemberNotFound",
      "userId": "userId_01EHWNCE74X7JSDV0X3SZ3KJNY"
    }
  }
}
```

:::

### Mutation inviteUser

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | String! | Yes | The email address to invite. |
| `expiresInDays` | Int | No | Number of days until the invitation expires. Defaults to the environment setting when omitted. |
| `roleSlug` | String | No | Slug of the role to grant on acceptance. Defaults to the organization default role when omitted. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `InvalidInvitationExpiry` | InvalidInvitationExpiry | The requested invitation expiry is outside the allowed range (1–30 days). |
| `InvalidInviteeEmail` | InvalidInviteeEmail | The provided email address is not valid. |
| `InvalidInviteeRole` | InvalidInviteeRole | The requested role is not valid for this organization. |
| `InviteeAlreadyInvited` | InviteeAlreadyInvited | This email already has a pending invitation. |
| `InviteeAlreadyMember` | InviteeAlreadyMember | A user with this email is already a member of the organization. |
| `InviteeEmailNotDeliverable` | InviteeEmailNotDeliverable | The invitee's email domain has no mail servers, so the invitation email cannot be delivered. |
| `OrganizationBlockedFromSendingInvites` | OrganizationBlockedFromSendingInvites | This organization is not allowed to send invites. |
| `UserInvited` | UserInvited | The invitation was created and the email sent. |

### Query organizationMemberships

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `after` | String | No |  |
| `before` | String | No |  |
| `limit` | Int | No |  |
| `order` | PaginationOrder | No | Enum represents the pagination order. |
| `roleSlug` | String | No | Filter members by role slug. |
| `search` | String | No | Filter members by name or email. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `data` | [OrganizationMember!]! | An organization member — a user with their membership status and assigned roles. |
| `listMetadata` | ListMetadata! |  |

### Query organization

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | ID! | Yes |  |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `allowProfilesOutsideOrganization` | Boolean! | Whether the organization allows profiles outside the organization domains. |
| `createdAt` | DateTime! |  |
| `id` | ID! |  |
| `name` | String! |  |
| `updatedAt` | DateTime! |  |

### Query organizations

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `id` | ID! |  |
| `isCurrent` | Boolean! | Whether this is the organization the token is currently scoped to. |
| `name` | String! |  |

### Mutation removeMember

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `userId` | ID! | Yes | The user ID of the member to remove. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `MemberIsManagedByDirectory` | MemberIsManagedByDirectory | The member is provisioned by a directory and cannot be removed. |
| `MemberNotFound` | MemberNotFound | No active member was found for the given user in the organization. |
| `MemberRemoved` | MemberRemoved | The member was removed from the organization. |

### Mutation resendInvitation

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `userId` | ID! | Yes | The ID of the user whose invitation should be resent. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `InvitationResent` | InvitationResent | The invitation was resent successfully. |
| `InviteeAlreadyAccepted` | InviteeAlreadyAccepted | The user has already accepted their invitation and is an active member. |
| `InviteeEmailNotDeliverable` | InviteeEmailNotDeliverable | The invitee's email domain has no mail servers, so the invitation email cannot be delivered. |
| `ResendInvitationNotFound` | ResendInvitationNotFound | No invitation exists for this user in this organization. |

### Mutation revokeInvitation

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `userId` | ID! | Yes | The ID of the user whose pending invitation should be revoked. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `InvitationNotFound` | InvitationNotFound | No pending invitation exists for this user in this organization. |
| `InvitationNotPending` | InvitationNotPending | The invitation is not pending (already accepted, expired, or revoked) and cannot be revoked. |
| `InvitationRevoked` | InvitationRevoked | The invitation was revoked. |

### Mutation updateMemberRole

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `roleSlugs` | [String!]! | Yes | Slugs of the roles to assign. When multiple roles are enabled for the environment, all provided roles are assigned; otherwise only the first slug is used. |
| `userId` | ID! | Yes | The user ID of the member to update. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `MemberNotFound` | MemberNotFound | No active member was found for the given user in the organization. |
| `MemberRoleUpdated` | MemberRoleUpdated | The member's role was updated. |
| `RoleNotFound` | RoleNotFound | No active roles with the given slugs exist in the environment. |