Clerk docs

Organizations

Organizations are used to group members under a common entity and provide shared access to resources.

https://clerk.com/docs/organizations/overview

Get a list of organizations for an instance

This request returns the list of organizations for an instance. Results can be paginated using the optional limit and offset query parameters. The organizations are ordered by descending creation date. Most recent organizations will be returned first.

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.

include_members_count
boolean

Flag to denote whether the member counts of each organization should be included in the response or not.

query
string

Returns organizations with ID, name, or slug that match the given query. Uses exact match for organization ID and partial match for name and slug.

order_by
string
Default: "-created_at"

Allows to return organizations in a particular order. At the moment, you can order the returned organizations either by their name, created_at or members_count. In order to specify the direction, you can use the +/- symbols prepended in the property to order by. For example, if you want organizations to be returned in descending order according to their created_at property, you can use -created_at. If you don't use + or -, then + is implied. Defaults to -created_at.

Responses
200

A list of organizations

400

Request was not successful

403

Authorization invalid

422

Invalid request parameters

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

Create an organization

Creates a new organization with the given name for an instance. In order to successfully create an organization you need to provide the ID of the User who will become the organization administrator. You can specify an optional slug for the new organization. If provided, the organization slug can contain only lowercase alphanumeric characters (letters and digits) and the dash "-". Organization slugs must be unique for the instance. You can provide additional metadata for the organization and set any custom attribute you want. Organizations support private and public metadata. Private metadata can only be accessed from the Backend API. Public metadata can be accessed from the Backend API, and are read-only from the Frontend API. The created_by user will see this as their [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
Request Body schema: application/json
name
required
string

The name of the new organization. May not contain URLs or HTML.

created_by
required
string

The ID of the User who will become the administrator for the new organization

private_metadata
object

Metadata saved on the organization, accessible only from the Backend API

public_metadata
object

Metadata saved on the organization, read-only from the Frontend API and fully accessible (read/write) from the Backend API

slug
string

A slug for the new organization. Can contain only lowercase alphanumeric characters and the dash "-". Must be unique for the instance.

max_allowed_memberships
integer

The maximum number of memberships allowed for this organization

created_at
string

A custom date/time denoting when the organization was created, specified in RFC3339 format (e.g. 2012-10-20T07:15:20.902Z).

Responses
200

An organization

400

Request was not successful

403

Authorization invalid

422

Invalid request parameters

post/organizations
Request samples
application/json
{
  • "name": "string",
  • "created_by": "string",
  • "private_metadata": { },
  • "public_metadata": { },
  • "slug": "string",
  • "max_allowed_memberships": 0,
  • "created_at": "string"
}
Response samples
application/json
{
  • "object": "organization",
  • "id": "string",
  • "name": "string",
  • "slug": "string",
  • "members_count": 0,
  • "max_allowed_memberships": 0,
  • "admin_delete_enabled": true,
  • "public_metadata": { },
  • "private_metadata": { },
  • "created_by": "string",
  • "created_at": 0,
  • "updated_at": 0
}

Retrieve an organization by ID or slug

Fetches the organization whose ID or slug matches the provided id_or_slug URL query parameter.

SecuritybearerAuth
Request
path Parameters
organization_id
required
string

The ID or slug of the organization

query Parameters
include_members_count
boolean

Flag to denote whether or not the organization's members count should be included in the response.

Responses
200

An organization

403

Authorization invalid

404

Resource not found

get/organizations/{organization_id}
Response samples
application/json
{
  • "object": "organization",
  • "id": "string",
  • "name": "string",
  • "slug": "string",
  • "members_count": 0,
  • "max_allowed_memberships": 0,
  • "admin_delete_enabled": true,
  • "public_metadata": { },
  • "private_metadata": { },
  • "created_by": "string",
  • "created_at": 0,
  • "updated_at": 0
}

Update an organization

Updates an existing organization

SecuritybearerAuth
Request
path Parameters
organization_id
required
string

The ID of the organization to update

Request Body schema: application/json
required
public_metadata
object

Metadata saved on the organization, that is visible to both your frontend and backend.

private_metadata
object

Metadata saved on the organization that is only visible to your backend.

name
string or null

The new name of the organization. May not contain URLs or HTML.

slug
string or null

The new slug of the organization, which needs to be unique in the instance

max_allowed_memberships
integer or null

The maximum number of memberships allowed for this organization

admin_delete_enabled
boolean or null

If true, an admin can delete this organization with the Frontend API.

created_at
string

A custom date/time denoting when the organization was created, specified in RFC3339 format (e.g. 2012-10-20T07:15:20.902Z).

Responses
200

An organization

402

Resource not found

404

Resource not found

422

Invalid request parameters

patch/organizations/{organization_id}
Request samples
application/json
{
  • "public_metadata": { },
  • "private_metadata": { },
  • "name": "string",
  • "slug": "string",
  • "max_allowed_memberships": 0,
  • "admin_delete_enabled": true,
  • "created_at": "string"
}
Response samples
application/json
{
  • "object": "organization",
  • "id": "string",
  • "name": "string",
  • "slug": "string",
  • "members_count": 0,
  • "max_allowed_memberships": 0,
  • "admin_delete_enabled": true,
  • "public_metadata": { },
  • "private_metadata": { },
  • "created_by": "string",
  • "created_at": 0,
  • "updated_at": 0
}

Delete an organization

Deletes the given organization. Please note that deleting an organization will also delete all memberships and invitations. This is not reversible.

SecuritybearerAuth
Request
path Parameters
organization_id
required
string

The ID of the organization to delete

Responses
200

Deleted Object

404

Resource not found

delete/organizations/{organization_id}
Response samples
application/json
{
  • "object": "string",
  • "id": "string",
  • "slug": "string",
  • "deleted": true
}

Merge and update metadata for an organization

Update organization metadata attributes by merging existing values with the provided parameters. Metadata values will be updated via a deep merge. Deep meaning 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 for which metadata will be merged or updated

Request Body schema: application/json
required
public_metadata
object

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

private_metadata
object

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

Responses
200

An organization

400

Request was not successful

401

Authentication invalid

404

Resource not found

422

Invalid request parameters

patch/organizations/{organization_id}/metadata
Request samples
application/json
{
  • "public_metadata": { },
  • "private_metadata": { }
}
Response samples
application/json
{
  • "object": "organization",
  • "id": "string",
  • "name": "string",
  • "slug": "string",
  • "members_count": 0,
  • "max_allowed_memberships": 0,
  • "admin_delete_enabled": true,
  • "public_metadata": { },
  • "private_metadata": { },
  • "created_by": "string",
  • "created_at": 0,
  • "updated_at": 0
}
➔ Next to Organization Invitations