Create an organization

Learn how to create an organization in your Clerk instance

Overview

Organizations are created by your end users. Whichever signed-in user creates an organization takes on the admin role for that organization.

The only required parameter when creating a new organization is the organization name, which can be any string. In React and Next.js applications, the useOrganizationList() hook returns the createOrganization method. In ClerkJS, the same method is available directly on the Clerk object.

The organization name can be updated by calling the organization.update() method.

When creating an organization, 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.

Using the Organizations Backend API, you can provide additional metadata for the organization and set custom attributes. Organizations support both 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.

Usage

Create a new organization

1
// Form to create a new organization. The current user
2
// will become the organization administrator.
3
import { useOrganizationList } from "@clerk/nextjs";
4
import { FormEventHandler, useState } from "react";
5

6
export default function CreateOrganization() {
7
  const { createOrganization } = useOrganizationList();
8
  const [organizationName, setOrganizationName] = useState("");
9

10
  const handleSubmit: FormEventHandler<HTMLFormElement> = (e) => {
11
    e.preventDefault();
12
    createOrganization({ name: organizationName });
13
    setOrganizationName("");
14
  };
15
  
16
  return (
17
    <form onSubmit={handleSubmit}>
18
      <input
19
        type="text"
20
        name="organizationName"
21
        value={organizationName}
22
        onChange={(e) => setOrganizationName(e.currentTarget.value)}
23
      />
24
      <button type="submit">Create organization</button>
25
    </form>
26
  );
27
}
28

1
// Form to create a new organization. The current user
2
// will become the organization administrator.
3
import { useOrganizationList } from "@clerk/clerk-react";
4
import { FormEventHandler, useState } from "react";
5

6
export default function CreateOrganization() {
7
  const { createOrganization } = useOrganizationList();
8
  const [organizationName, setOrganizationName] = useState("");
9

10
  const handleSubmit: FormEventHandler<HTMLFormElement> = (e) => {
11
    e.preventDefault();
12
    createOrganization({ name: organizationName });
13
    setOrganizationName("");
14
  };
15
  
16
  return (
17
    <form onSubmit={handleSubmit}>
18
      <input
19
        type="text"
20
        name="organizationName"
21
        value={organizationName}
22
        onChange={(e) => setOrganizationName(e.currentTarget.value)}
23
      />
24
      <button type="submit">Create organization</button>
25
    </form>
26
  );
27
}
28

1
<!-- Form to create an organization -->
2
<form id="new_organization">
3
  <div>
4
    <label>Name</label>
5
    <br />
6
    <input name="name" />
7
  </div>
8
  <button>Create organization</button>
9
</form>
10

11
<script>
12
  const form = document.getElementById("new_organization");
13
  form.addEventListener('submit', function(e) {
14
    e.preventDefault();
15
    const inputEl = form.getElementsByTagName("input")[0];
16
    if (!inputEl) {
17
      return;
18
    }
19
    try {
20
      await window.Clerk.createOrganization({ name: inputEl.value });
21
    } catch (err) {
22
      console.error(err);
23
    }
24
  });
25
</script>
26

Update organization name

1
// pages/organizations/[id]/edit.js
2
import { useState, useEffect } from 'react';
3
import { useRouter } from 'next/router';
4
import { useOrganization } from '@clerk/nextjs';
5

6
export default function EditOrganization() {
7
  const [name, setName] = useState('');
8

9
  const router = useRouter();
10

11
  const { organization } = useOrganization();
12

13
  useEffect(() => {
14
    if (!organization) {
15
      return;
16
    }
17
    setName(organization.name);
18
  }, [organization]);
19

20
  async function submit(e) {
21
    e.preventDefault();
22
    try {
23
      await organization.update({ name });
24
      router.push(`/organizations/${organization.id}`);
25
    } catch (err) {
26
      console.error(err);
27
    }
28
  }
29

30
  if (!organization) {
31
    return null;
32
  }
33

34
  return (
35
    <div>
36
      <h2>Edit organization</h2>
37
      <form onSubmit={submit}>
38
        <div>
39
          <label>Name</label>
40
          <br />
41
          <input
42
            name="name"
43
            value={name}
44
            onChange={(e) => setName(e.target.value)}
45
          />
46
        </div>
47
        <button>Save</button>
48
      </form>
49
    </div>
50
  );
51
}
52

1
import { useState, useEffect } from 'react';
2
import { useOrganization } from '@clerk/react';
3

4
export default function EditOrganization({ organizationId }) {
5
  const [name, setName] = useState('');
6

7
  const { organization } = useOrganization();
8

9
  useEffect(() => {
10
    if (!organization) {
11
      return;
12
    }
13
    setName(organization.name);
14
  }, [organization]);
15

16
  async function submit(e) {
17
    e.preventDefault();
18
    try {
19
      await organization.update({ name });
20
      router.push(`/organizations/${organization.id}`);
21
    } catch (err) {
22
      console.error(err);
23
    }
24
  }
25

26
  if (!organization) {
27
    return null;
28
  }
29

30
  return (
31
    <div>
32
      <h2>Edit organization</h2>
33
      <form onSubmit={submit}>
34
        <div>
35
          <label>Name</label>
36
          <br />
37
          <input
38
            name="name"
39
            value={name}
40
            onChange={(e) => setName(e.target.value)}
41
          />
42
        </div>
43
        <button>Save</button>
44
      </form>
45
    </div>
46
  );
47
}
48

1
<form id="edit_organization">
2
  <div>
3
    <label>Name</label>
4
    <br />
5
    <input name="name" />
6
  </div>
7
  <button>Save</button>
8
</form>
9

10
<script>
11
  async function init() {
12
    // This is the current organization ID.
13
    const organizationId = "org_XXXXXXX";
14
    const organizationMemberships = await window.Clerk.getOrganizationMemberships()
15
    const currentMembership = organizationMemberships.find(membership 
16
      => membership.organization.id === organizationId);
17
    const currentOrganization = currentMembership.organization;
18
    
19
    if (!currentOrganization) {
20
      return;
21
    }
22
    
23
    editOrganization(currentOrganization);
24
  }
25
  
26
  async function editOrganization(organization) {
27
    const form = document.getElementById("edit_organization");
28
    const inputEl = form.getElementsByTagName("input")[0];
29
    if (inputEl) {
30
      inputEl.value = organization.name;
31
    }
32
    
33
    form.addEventListener('submit', function(e) {
34
      e.preventDefault();
35
      const inputEl = form.getElementsByTagName("input")[0];
36
      if (!inputEl) {
37
        return;
38
      }
39
      try {
40
        await organization.update({ name: inputEl.value });
41
      } catch (err) {
42
        console.error(err);
43
      }
44
    });
45
  }
46
  
47
  init();
48
</script>