(organizations)
Organizations are used to group members under a common entity and provide shared access to resources. https://clerk.com/docs/organizations/overview
- 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
- mergeMetadata - Merge and update metadata for an organization
- uploadLogo - Upload a logo for the organization
- deleteLogo - Delete the organization's logo.
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.
declare(strict_types=1);
require 'vendor/autoload.php';
use Clerk\Backend;
use Clerk\Backend\Models\Operations;
$security = '<YOUR_BEARER_TOKEN_HERE>';
$sdk = Backend\ClerkBackend::builder()->setSecurity($security)->build();
$request = new Operations\ListOrganizationsRequest();
$response = $sdk->organizations->list(
request: $request
);
if ($response->organizations !== null) {
// handle response
}
Parameter | Type | Required | Description |
---|---|---|---|
$request |
Operations\ListOrganizationsRequest | ✔️ | The request object to use for the request. |
?Operations\ListOrganizationsResponse
Error Type | Status Code | Content Type |
---|---|---|
Errors\ClerkErrors67 | 400, 403, 422 | application/json |
Errors\SDKException | 4XX, 5XX | */* |
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.
declare(strict_types=1);
require 'vendor/autoload.php';
use Clerk\Backend;
use Clerk\Backend\Models\Operations;
$security = '<YOUR_BEARER_TOKEN_HERE>';
$sdk = Backend\ClerkBackend::builder()->setSecurity($security)->build();
$request = new Operations\CreateOrganizationRequestBody(
name: '<value>',
createdBy: '<value>',
);
$response = $sdk->organizations->create(
request: $request
);
if ($response->organization !== null) {
// handle response
}
Parameter | Type | Required | Description |
---|---|---|---|
$request |
Operations\CreateOrganizationRequestBody | ✔️ | The request object to use for the request. |
?Operations\CreateOrganizationResponse
Error Type | Status Code | Content Type |
---|---|---|
Errors\ClerkErrors68 | 400, 403, 422 | application/json |
Errors\SDKException | 4XX, 5XX | */* |
Fetches the organization whose ID or slug matches the provided id_or_slug
URL query parameter.
declare(strict_types=1);
require 'vendor/autoload.php';
use Clerk\Backend;
$security = '<YOUR_BEARER_TOKEN_HERE>';
$sdk = Backend\ClerkBackend::builder()->setSecurity($security)->build();
$response = $sdk->organizations->get(
organizationId: '<id>',
includeMembersCount: false
);
if ($response->organization !== null) {
// handle response
}
Parameter | Type | Required | Description |
---|---|---|---|
organizationId |
string | ✔️ | The ID or slug of the organization |
includeMembersCount |
?bool | ➖ | Flag to denote whether or not the organization's members count should be included in the response. |
?Operations\GetOrganizationResponse
Error Type | Status Code | Content Type |
---|---|---|
Errors\ClerkErrors69 | 403, 404 | application/json |
Errors\SDKException | 4XX, 5XX | */* |
Updates an existing organization
declare(strict_types=1);
require 'vendor/autoload.php';
use Clerk\Backend;
use Clerk\Backend\Models\Operations;
$security = '<YOUR_BEARER_TOKEN_HERE>';
$sdk = Backend\ClerkBackend::builder()->setSecurity($security)->build();
$requestBody = new Operations\UpdateOrganizationRequestBody();
$response = $sdk->organizations->update(
organizationId: '<id>',
requestBody: $requestBody
);
if ($response->organization !== null) {
// handle response
}
Parameter | Type | Required | Description |
---|---|---|---|
organizationId |
string | ✔️ | The ID of the organization to update |
requestBody |
Operations\UpdateOrganizationRequestBody | ✔️ | N/A |
?Operations\UpdateOrganizationResponse
Error Type | Status Code | Content Type |
---|---|---|
Errors\ClerkErrors70 | 402, 404, 422 | application/json |
Errors\SDKException | 4XX, 5XX | */* |
Deletes the given organization. Please note that deleting an organization will also delete all memberships and invitations. This is not reversible.
declare(strict_types=1);
require 'vendor/autoload.php';
use Clerk\Backend;
$security = '<YOUR_BEARER_TOKEN_HERE>';
$sdk = Backend\ClerkBackend::builder()->setSecurity($security)->build();
$response = $sdk->organizations->delete(
organizationId: '<id>'
);
if ($response->deletedObject !== null) {
// handle response
}
Parameter | Type | Required | Description |
---|---|---|---|
organizationId |
string | ✔️ | The ID of the organization to delete |
?Operations\DeleteOrganizationResponse
Error Type | Status Code | Content Type |
---|---|---|
Errors\ClerkErrors71 | 404 | application/json |
Errors\SDKException | 4XX, 5XX | */* |
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
.
declare(strict_types=1);
require 'vendor/autoload.php';
use Clerk\Backend;
use Clerk\Backend\Models\Operations;
$security = '<YOUR_BEARER_TOKEN_HERE>';
$sdk = Backend\ClerkBackend::builder()->setSecurity($security)->build();
$requestBody = new Operations\MergeOrganizationMetadataRequestBody();
$response = $sdk->organizations->mergeMetadata(
organizationId: '<id>',
requestBody: $requestBody
);
if ($response->organization !== null) {
// handle response
}
Parameter | Type | Required | Description |
---|---|---|---|
organizationId |
string | ✔️ | The ID of the organization for which metadata will be merged or updated |
requestBody |
Operations\MergeOrganizationMetadataRequestBody | ✔️ | N/A |
?Operations\MergeOrganizationMetadataResponse
Error Type | Status Code | Content Type |
---|---|---|
Errors\ClerkErrors71 | 400, 401, 404, 422 | application/json |
Errors\SDKException | 4XX, 5XX | */* |
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
.
declare(strict_types=1);
require 'vendor/autoload.php';
use Clerk\Backend;
use Clerk\Backend\Models\Operations;
$security = '<YOUR_BEARER_TOKEN_HERE>';
$sdk = Backend\ClerkBackend::builder()->setSecurity($security)->build();
$requestBody = new Operations\UploadOrganizationLogoRequestBody(
file: new Operations\UploadOrganizationLogoFile(
fileName: 'example.file',
content: '0x0DDEE4e6Ea',
),
);
$response = $sdk->organizations->uploadLogo(
organizationId: '<id>',
requestBody: $requestBody
);
if ($response->organizationWithLogo !== null) {
// handle response
}
Parameter | Type | Required | Description |
---|---|---|---|
organizationId |
string | ✔️ | The ID of the organization for which to upload a logo |
requestBody |
?Operations\UploadOrganizationLogoRequestBody | ➖ | N/A |
?Operations\UploadOrganizationLogoResponse
Error Type | Status Code | Content Type |
---|---|---|
Errors\ClerkErrors72 | 400, 403, 404, 413 | application/json |
Errors\SDKException | 4XX, 5XX | */* |
Delete the organization's logo.
declare(strict_types=1);
require 'vendor/autoload.php';
use Clerk\Backend;
$security = '<YOUR_BEARER_TOKEN_HERE>';
$sdk = Backend\ClerkBackend::builder()->setSecurity($security)->build();
$response = $sdk->organizations->deleteLogo(
organizationId: '<id>'
);
if ($response->organization !== null) {
// handle response
}
Parameter | Type | Required | Description |
---|---|---|---|
organizationId |
string | ✔️ | The ID of the organization for which the logo will be deleted. |
?Operations\DeleteOrganizationLogoResponse
Error Type | Status Code | Content Type |
---|---|---|
Errors\ClerkErrors73 | 404 | application/json |
Errors\SDKException | 4XX, 5XX | */* |