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
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."

user_id
Array of strings

Returns users with the user ids specified. For each user id, the + and - can be prepended to the id, which denote whether the respective user id should be included or excluded from the result set. Accepts up to 100 user ids. Any user ids not found are ignored.

email_address
Array of strings

Returns users with the specified email addresses. Accepts up to 100 email addresses. Any email addresses not found are ignored.

phone_number
Array of strings

Returns users with the specified phone numbers. Accepts up to 100 phone numbers. Any phone numbers not found are ignored.

username
Array of strings

Returns users with the specified usernames. Accepts up to 100 usernames. Any usernames not found are ignored.

web3_wallet
Array of strings

Returns users with the specified web3 wallet addresses. Accepts up to 100 web3 wallet addresses. Any web3 wallet addressed not found are ignored.

role
Array of strings

Returns users with the specified roles. Accepts up to 100 roles. Any roles not found are ignored.

query
string

Returns users that match the given query. For possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user ids, first and last names. The query value doesn't need to match the exact value you are looking for, it is capable of partial matches as well.

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
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.

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
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.

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.

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