OrganizationsSDK

(organizations)

Overview

Organizations are used to group members under a common entity and provide shared access to resources. https://clerk.com/docs/organizations/overview

Available Operations

list - Get a list of organizations for an instance
create - Create an organization
get - Retrieve an organization by ID or slug
update - Update an organization
delete - Delete an organization
merge_metadata - Merge and update metadata for an organization
upload_logo - Upload a logo for the organization
delete_logo - Delete the organization's logo.

list

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.

Example Usage

from clerk_backend_api import Clerk

with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as s:
    res = s.organizations.list(limit=20, offset=10, include_members_count=False, query="clerk", order_by="-name")

    if res is not None:
        # handle response
        pass

Parameters

Parameter	Type	Required	Description	Example
`limit`	Optional[int]	➖	Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`.	20
`offset`	Optional[int]	➖	Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.	10
`include_members_count`	Optional[bool]	➖	Flag to denote whether the member counts of each organization should be included in the response or not.	false
`query`	Optional[str]	➖	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.	clerk
`order_by`	Optional[str]	➖	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`.	-name
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.Organizations

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 403, 422	application/json
models.SDKError	4XX, 5XX	/

create

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.

Example Usage

from clerk_backend_api import Clerk

with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as s:
    res = s.organizations.create(name="NewOrg", created_by="user_123", private_metadata={
        "internal_code": "ABC123",
    }, public_metadata={
        "public_event": "Annual Summit",
    }, slug="neworg", max_allowed_memberships=100, created_at="<value>")

    if res is not None:
        # handle response
        pass

Parameters

Parameter	Type	Required	Description	Example
`name`	str	✔️	The name of the new organization. May not contain URLs or HTML.	NewOrg
`created_by`	str	✔️	The ID of the User who will become the administrator for the new organization	user_123
`private_metadata`	Dict[str, Any]	➖	Metadata saved on the organization, accessible only from the Backend API	{ "internal_code": "ABC123" }
`public_metadata`	Dict[str, Any]	➖	Metadata saved on the organization, read-only from the Frontend API and fully accessible (read/write) from the Backend API	{ "public_event": "Annual Summit" }
`slug`	Optional[str]	➖	A slug for the new organization. Can contain only lowercase alphanumeric characters and the dash "-". Must be unique for the instance.	neworg
`max_allowed_memberships`	Optional[int]	➖	The maximum number of memberships allowed for this organization	100
`created_at`	Optional[str]	➖	A custom date/time denoting when the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.Organization

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 403, 422	application/json
models.SDKError	4XX, 5XX	/

get

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

Example Usage

from clerk_backend_api import Clerk

with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as s:
    res = s.organizations.get(organization_id="org_123", include_members_count=False)

    if res is not None:
        # handle response
        pass

Parameters

Parameter	Type	Required	Description	Example
`organization_id`	str	✔️	The ID or slug of the organization	org_123
`include_members_count`	Optional[bool]	➖	Flag to denote whether or not the organization's members count should be included in the response.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.Organization

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	403, 404	application/json
models.SDKError	4XX, 5XX	/

update

Updates an existing organization

Example Usage

from clerk_backend_api import Clerk

with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as s:
    res = s.organizations.update(organization_id="org_123_update", public_metadata={

    }, private_metadata={

    }, name="New Organization Name", slug="new-org-slug", max_allowed_memberships=100, admin_delete_enabled=True, created_at="<value>", additional_properties={

    })

    if res is not None:
        # handle response
        pass

Parameters

Parameter	Type	Required	Description	Example
`organization_id`	str	✔️	The ID of the organization to update	org_123_update
`public_metadata`	Dict[str, Any]	➖	Metadata saved on the organization, that is visible to both your frontend and backend.	{}
`private_metadata`	Dict[str, Any]	➖	Metadata saved on the organization that is only visible to your backend.	{}
`name`	OptionalNullable[str]	➖	The new name of the organization. May not contain URLs or HTML.	New Organization Name
`slug`	OptionalNullable[str]	➖	The new slug of the organization, which needs to be unique in the instance	new-org-slug
`max_allowed_memberships`	OptionalNullable[int]	➖	The maximum number of memberships allowed for this organization	100
`admin_delete_enabled`	OptionalNullable[bool]	➖	If true, an admin can delete this organization with the Frontend API.	true
`created_at`	Optional[str]	➖	A custom date/time denoting when the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).
`additional_properties`	Dict[str, Any]	➖	N/A
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.Organization

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	402, 404, 422	application/json
models.SDKError	4XX, 5XX	/

delete

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

Example Usage

from clerk_backend_api import Clerk

with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as s:
    res = s.organizations.delete(organization_id="org_321_delete")

    if res is not None:
        # handle response
        pass

Parameters

Parameter	Type	Required	Description	Example
`organization_id`	str	✔️	The ID of the organization to delete	org_321_delete
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.DeletedObject

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	404	application/json
models.SDKError	4XX, 5XX	/

merge_metadata

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.

Example Usage

from clerk_backend_api import Clerk

with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as s:
    res = s.organizations.merge_metadata(organization_id="org_12345", public_metadata={
        "announcement": "We are opening a new office!",
    }, private_metadata={
        "internal_use_only": "Future plans discussion.",
    }, additional_properties={

    })

    if res is not None:
        # handle response
        pass

Parameters

Parameter	Type	Required	Description	Example
`organization_id`	str	✔️	The ID of the organization for which metadata will be merged or updated	org_12345
`public_metadata`	Dict[str, Any]	➖	Metadata saved on the organization, that is visible to both your frontend and backend. The new object will be merged with the existing value.	{ "announcement": "We are opening a new office!" }
`private_metadata`	Dict[str, Any]	➖	Metadata saved on the organization that is only visible to your backend. The new object will be merged with the existing value.	{ "internal_use_only": "Future plans discussion." }
`additional_properties`	Dict[str, Any]	➖	N/A
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.Organization

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 404, 422	application/json
models.SDKError	4XX, 5XX	/

upload_logo

Set or replace an organization's logo, by uploading an image file. This endpoint uses the multipart/form-data request content type and accepts a file of image type. The file size cannot exceed 10MB. Only the following file content types are supported: image/jpeg, image/png, image/gif, image/webp, image/x-icon, image/vnd.microsoft.icon.

Example Usage

from clerk_backend_api import Clerk

with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as s:
    res = s.organizations.upload_logo(organization_id="org_12345", file={
        "file_name": "example.file",
        "content": open("example.file", "rb"),
        "content_type": "<value>",
    }, uploader_user_id="user_67890")

    if res is not None:
        # handle response
        pass

Parameters

Parameter	Type	Required	Description	Example
`organization_id`	str	✔️	The ID of the organization for which to upload a logo	org_12345
`file`	models.UploadOrganizationLogoFile	✔️	N/A	path/to/your/logo.png
`uploader_user_id`	Optional[str]	➖	The ID of the user that will be credited with the image upload.	user_67890
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.OrganizationWithLogo

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 403, 404, 413	application/json
models.SDKError	4XX, 5XX	/

delete_logo

Delete the organization's logo.

Example Usage

from clerk_backend_api import Clerk

with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as s:
    res = s.organizations.delete_logo(organization_id="org_12345")

    if res is not None:
        # handle response
        pass

Parameters

Parameter	Type	Required	Description	Example
`organization_id`	str	✔️	The ID of the organization for which the logo will be deleted.	org_12345
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.Organization

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	404	application/json
models.SDKError	4XX, 5XX	/

Files

README.md

Latest commit

History

README.md

File metadata and controls

OrganizationsSDK

Overview

Available Operations

list

Example Usage

Parameters

Response

Errors

create

Example Usage

Parameters

Response

Errors

get

Example Usage

Parameters

Response

Errors

update

Example Usage

Parameters

Response

Errors

delete

Example Usage

Parameters

Response

Errors

merge_metadata

Example Usage

Parameters

Response

Errors

upload_logo

Example Usage

Parameters

Response

Errors

delete_logo

Example Usage

Parameters

Response

Errors