Clerk docs

Organization Memberships

Manage member roles in an organization.

https://clerk.com/docs/organizations/manage-member-roles

Create a new organization membership

Adds a user as a member to the given organization. Only users in the same instance as the organization can be added as members.

This organization will be the user's [active organization] (https://clerk.com/docs/organizations/overview#active-organization) the next time they create a session, presuming they don't explicitly set a different organization as active before then.

SecuritybearerAuth
Request
path Parameters
organization_id
required
string

The ID of the organization where the new membership will be created

Request Body schema: application/json
required
user_id
required
string

The ID of the user that will be added as a member in the organization. The user needs to exist in the same instance as the organization and must not be a member of the given organization already.

role
required
string

The role that the new member will have in the organization.

Responses
200

Success

400

Request was not successful

403

Authorization invalid

404

Resource not found

422

Invalid request parameters

post/organizations/{organization_id}/memberships
Request samples
application/json
{
  • "user_id": "string",
  • "role": "string"
}
Response samples
application/json
{
  • "id": "string",
  • "object": "organization_membership",
  • "role": "string",
  • "role_name": "string",
  • "permissions": [
    ],
  • "public_metadata": { },
  • "private_metadata": { },
  • "organization": {
    },
  • "public_user_data": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Get a list of all members of an organization

Retrieves all user memberships for the given organization

SecuritybearerAuth
Request
path Parameters
organization_id
required
string

The organization ID.

query Parameters
limit
integer [ 1 .. 500 ]
Default: 10

Applies a limit to the number of results returned. Can be used for paginating the results together with offset.

offset
integer >= 0
Default: 0

Skip the first offset results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with limit.

order_by
string

Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username. By prepending one of those values with + or -, we can choose to sort in ascending (ASC) or descending (DESC) order."

email_address_query
string

Returns users with emails that match the given query, via case-insensitive partial match. For example, email_address_query=ello will match a user with the email HELLO@example.com.

phone_number_query
string

Returns users with phone numbers that match the given query, via case-insensitive partial match. For example, phone_number_query=555 will match a user with the phone number +1555xxxxxxx.

username_query
string

Returns users with usernames that match the given query, via case-insensitive partial match. For example, username_query=CoolUser will match a user with the username SomeCoolUser.

name_query
string

Returns users with names that match the given query, via case-insensitive partial match.

last_active_at_before
integer

Returns users whose last session activity was before the given date (with millisecond precision). Example: use 1700690400000 to retrieve users whose last session activity was before 2023-11-23.

Example: last_active_at_before=1700690400000
last_active_at_after
integer

Returns users whose last session activity was after the given date (with millisecond precision). Example: use 1700690400000 to retrieve users whose last session activity was after 2023-11-23.

Example: last_active_at_after=1700690400000
created_at_before
integer

Returns users who have been created before the given date (with millisecond precision). Example: use 1730160000000 to retrieve users who have been created before 2024-10-29.

Example: created_at_before=1730160000000
created_at_after
integer

Returns users who have been created after the given date (with millisecond precision). Example: use 1730160000000 to retrieve users who have been created after 2024-10-29.

Example: created_at_after=1730160000000
Responses
200

A list of organization memberships

401

Authentication invalid

422

Invalid request parameters

get/organizations/{organization_id}/memberships
Response samples
application/json
{
  • "data": [
    ],
  • "total_count": 0
}

Update an organization membership

Updates the properties of an existing organization membership

SecuritybearerAuth
Request
path Parameters
organization_id
required
string

The ID of the organization the membership belongs to

user_id
required
string

The ID of the user that this membership belongs to

Request Body schema: application/json
required
role
required
string

The new role of the given membership.

Responses
200

Success

400

Request was not successful

404

Resource not found

422

Invalid request parameters

patch/organizations/{organization_id}/memberships/{user_id}
Request samples
application/json
{
  • "role": "string"
}
Response samples
application/json
{
  • "id": "string",
  • "object": "organization_membership",
  • "role": "string",
  • "role_name": "string",
  • "permissions": [
    ],
  • "public_metadata": { },
  • "private_metadata": { },
  • "organization": {
    },
  • "public_user_data": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Remove a member from an organization

Removes the given membership from the organization

SecuritybearerAuth
Request
path Parameters
organization_id
required
string

The ID of the organization the membership belongs to

user_id
required
string

The ID of the user that this membership belongs to

Responses
200

Success

400

Request was not successful

401

Authentication invalid

404

Resource not found

delete/organizations/{organization_id}/memberships/{user_id}
Response samples
application/json
{
  • "id": "string",
  • "object": "organization_membership",
  • "role": "string",
  • "role_name": "string",
  • "permissions": [
    ],
  • "public_metadata": { },
  • "private_metadata": { },
  • "organization": {
    },
  • "public_user_data": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Merge and update organization membership metadata

Update an organization membership's metadata attributes by merging existing values with the provided parameters. Metadata values will be updated via a deep merge. Deep means that any nested JSON objects will be merged as well. You can remove metadata keys at any level by setting their value to null.

SecuritybearerAuth
Request
path Parameters
organization_id
required
string

The ID of the organization the membership belongs to

user_id
required
string

The ID of the user that this membership belongs to

Request Body schema: application/json
object

Metadata saved on the organization membership, that is visible to both your frontend and backend. The new object will be merged with the existing value.

object

Metadata saved on the organization membership that is only visible to your backend. The new object will be merged with the existing value.

Responses
200

Success

400

Request was not successful

404

Resource not found

422

Invalid request parameters

patch/organizations/{organization_id}/memberships/{user_id}/metadata
Request samples
application/json
{
  • "public_metadata": { },
  • "private_metadata": { }
}
Response samples
application/json
{
  • "id": "string",
  • "object": "organization_membership",
  • "role": "string",
  • "role_name": "string",
  • "permissions": [
    ],
  • "public_metadata": { },
  • "private_metadata": { },
  • "organization": {
    },
  • "public_user_data": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Get a list of all organization memberships within an instance.

Retrieves all organization user memberships for the given instance.

SecuritybearerAuth
Request
query Parameters
limit
integer [ 1 .. 500 ]
Default: 10

Applies a limit to the number of results returned. Can be used for paginating the results together with offset.

offset
integer >= 0
Default: 0

Skip the first offset results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with limit.

order_by
string

Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username. By prepending one of those values with + or -, we can choose to sort in ascending (ASC) or descending (DESC) order.

Responses
200

A list of organization memberships

400

Request was not successful

401

Authentication invalid

422

Invalid request parameters

500

Request was not successful

get/organization_memberships
Response samples
application/json
{
  • "data": [
    ],
  • "total_count": 0
}
➔ Next to Phone Numbers