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
number [ 1 .. 500 ]
Default: 10

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

offset
number >= 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

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
required
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
number [ 1 .. 500 ]
Default: 10

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

offset
number >= 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