Clerk API (unofficial showcase)
POST/organizations

Create an organization

Creates a new organization with the given name for an instance. 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 the next time they create a session, presuming they don't explicitly set a different organization as active before then.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

8 body fields
namestringrequired
The name of the new organization. May not contain URLs or HTML. Max length: 256
created_bystringoptional
The ID of the User who will become the administrator for the new organization
private_metadataobjectoptional
Metadata saved on the organization, accessible only from the Backend API
public_metadataobjectoptional
Metadata saved on the organization, read-only from the Frontend API and fully accessible (read/write) from the Backend API
slugstringoptional
A slug for the new organization. Can contain only lowercase alphanumeric characters and the dash "-". Must be unique for the instance. This field should only be included when slugs are enabled in the organization settings, refer to our [documentation](https://clerk.com/docs/guides/organizations/overview#organization-slugs).
max_allowed_membershipsintegeroptional
The maximum number of memberships allowed for this organization
created_atstringoptional
A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).
role_set_keystringoptional
The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization.

5 status codes
200An organization
objectstringrequired
Allowed:organization
idstringrequired
namestringrequired
slugstringrequired
image_urlstringoptional
has_imagebooleanrequired
members_countintegeroptional
missing_member_with_elevated_permissionsbooleanoptional
pending_invitations_countintegeroptional
max_allowed_membershipsintegerrequired
admin_delete_enabledbooleanrequired
self_serve_sso_enabledbooleanoptional
Whether this organization can configure self-serve enterprise SSO.
self_serve_directory_sync_enabledbooleanoptional
Whether this organization can configure self-serve Directory Sync (SCIM).
public_metadataobjectrequired
private_metadataobjectoptional
created_bystringoptional
created_atintegerrequired
Unix timestamp of creation.
updated_atintegerrequired
Unix timestamp of last update.
last_active_atintegeroptional
Unix timestamp of last activity.
role_set_keystringoptional
The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) assigned to this organization.
400Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
402Payment required
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
403Authorization invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Invalid request parameters
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned: Request was not successful. A 402 is returned: Payment required. A 403 is returned: Authorization invalid. A 422 is returned: Invalid request parameters.