Skip to content

Latest commit

 

History

History
383 lines (271 loc) · 23.7 KB

README.md

File metadata and controls

383 lines (271 loc) · 23.7 KB

Organizations

(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
  • MergeMetadata - Merge and update metadata for an organization
  • UploadLogo - Upload a logo for the organization
  • DeleteLogo - 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

using Clerk.BackendAPI;
using Clerk.BackendAPI.Models.Operations;
using Clerk.BackendAPI.Models.Components;

var sdk = new ClerkBackendApi(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

ListOrganizationsRequest req = new ListOrganizationsRequest() {
    Limit = 20,
    Offset = 10,
    IncludeMembersCount = false,
    Query = "clerk",
    OrderBy = "-name",
};

var res = await sdk.Organizations.ListAsync(req);

// handle response

Parameters

Parameter Type Required Description
request ListOrganizationsRequest ✔️ The request object to use for the request.

Response

ListOrganizationsResponse

Errors

Error Type Status Code Content Type
Clerk.BackendAPI.Models.Errors.ClerkErrors 400, 403, 422 application/json
Clerk.BackendAPI.Models.Errors.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

using Clerk.BackendAPI;
using Clerk.BackendAPI.Models.Operations;
using System.Collections.Generic;
using Clerk.BackendAPI.Models.Components;

var sdk = new ClerkBackendApi(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

CreateOrganizationRequestBody req = new CreateOrganizationRequestBody() {
    Name = "NewOrg",
    CreatedBy = "user_123",
    PrivateMetadata = new Dictionary<string, object>() {
        { "internal_code", "ABC123" },
    },
    PublicMetadata = new Dictionary<string, object>() {
        { "public_event", "Annual Summit" },
    },
    Slug = "neworg",
    MaxAllowedMemberships = 100,
};

var res = await sdk.Organizations.CreateAsync(req);

// handle response

Parameters

Parameter Type Required Description
request CreateOrganizationRequestBody ✔️ The request object to use for the request.

Response

CreateOrganizationResponse

Errors

Error Type Status Code Content Type
Clerk.BackendAPI.Models.Errors.ClerkErrors 400, 403, 422 application/json
Clerk.BackendAPI.Models.Errors.SDKError 4XX, 5XX */*

Get

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

Example Usage

using Clerk.BackendAPI;
using Clerk.BackendAPI.Models.Operations;
using Clerk.BackendAPI.Models.Components;

var sdk = new ClerkBackendApi(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

var res = await sdk.Organizations.GetAsync(
    organizationId: "org_123",
    includeMembersCount: false
);

// handle response

Parameters

Parameter Type Required Description Example
OrganizationId string ✔️ The ID or slug of the organization org_123
IncludeMembersCount bool ➖ Flag to denote whether or not the organization's members count should be included in the response.

Response

GetOrganizationResponse

Errors

Error Type Status Code Content Type
Clerk.BackendAPI.Models.Errors.ClerkErrors 403, 404 application/json
Clerk.BackendAPI.Models.Errors.SDKError 4XX, 5XX */*

Update

Updates an existing organization

Example Usage

using Clerk.BackendAPI;
using Clerk.BackendAPI.Models.Operations;
using System.Collections.Generic;
using Clerk.BackendAPI.Models.Components;

var sdk = new ClerkBackendApi(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

var res = await sdk.Organizations.UpdateAsync(
    organizationId: "org_123_update",
    requestBody: new UpdateOrganizationRequestBody() {
        PublicMetadata = new Dictionary<string, object>() {

        },
        PrivateMetadata = new Dictionary<string, object>() {

        },
        Name = "New Organization Name",
        Slug = "new-org-slug",
        MaxAllowedMemberships = 100,
        AdminDeleteEnabled = true,
    }
);

// handle response

Parameters

Parameter Type Required Description Example
OrganizationId string ✔️ The ID of the organization to update org_123_update
RequestBody UpdateOrganizationRequestBody ✔️ N/A

Response

UpdateOrganizationResponse

Errors

Error Type Status Code Content Type
Clerk.BackendAPI.Models.Errors.ClerkErrors 402, 404, 422 application/json
Clerk.BackendAPI.Models.Errors.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

using Clerk.BackendAPI;
using Clerk.BackendAPI.Models.Operations;
using Clerk.BackendAPI.Models.Components;

var sdk = new ClerkBackendApi(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

var res = await sdk.Organizations.DeleteAsync(organizationId: "org_321_delete");

// handle response

Parameters

Parameter Type Required Description Example
OrganizationId string ✔️ The ID of the organization to delete org_321_delete

Response

DeleteOrganizationResponse

Errors

Error Type Status Code Content Type
Clerk.BackendAPI.Models.Errors.ClerkErrors 404 application/json
Clerk.BackendAPI.Models.Errors.SDKError 4XX, 5XX */*

MergeMetadata

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

using Clerk.BackendAPI;
using Clerk.BackendAPI.Models.Operations;
using System.Collections.Generic;
using Clerk.BackendAPI.Models.Components;

var sdk = new ClerkBackendApi(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

var res = await sdk.Organizations.MergeMetadataAsync(
    organizationId: "org_12345",
    requestBody: new MergeOrganizationMetadataRequestBody() {
        PublicMetadata = new Dictionary<string, object>() {
            { "announcement", "We are opening a new office!" },
        },
        PrivateMetadata = new Dictionary<string, object>() {
            { "internal_use_only", "Future plans discussion." },
        },
    }
);

// handle response

Parameters

Parameter Type Required Description Example
OrganizationId string ✔️ The ID of the organization for which metadata will be merged or updated org_12345
RequestBody MergeOrganizationMetadataRequestBody ✔️ N/A

Response

MergeOrganizationMetadataResponse

Errors

Error Type Status Code Content Type
Clerk.BackendAPI.Models.Errors.ClerkErrors 400, 401, 404, 422 application/json
Clerk.BackendAPI.Models.Errors.SDKError 4XX, 5XX */*

UploadLogo

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

using Clerk.BackendAPI;
using Clerk.BackendAPI.Models.Operations;
using Clerk.BackendAPI.Models.Components;

var sdk = new ClerkBackendApi(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

var res = await sdk.Organizations.UploadLogoAsync(
    organizationId: "org_12345",
    requestBody: new UploadOrganizationLogoRequestBody() {
        UploaderUserId = "user_67890",
        File = new UploadOrganizationLogoFile() {
            FileName = "example.file",
            Content = System.Text.Encoding.UTF8.GetBytes("0x0DDEE4e6Ea"),
        },
    }
);

// handle response

Parameters

Parameter Type Required Description Example
OrganizationId string ✔️ The ID of the organization for which to upload a logo org_12345
RequestBody UploadOrganizationLogoRequestBody ✔️ N/A

Response

UploadOrganizationLogoResponse

Errors

Error Type Status Code Content Type
Clerk.BackendAPI.Models.Errors.ClerkErrors 400, 403, 404, 413 application/json
Clerk.BackendAPI.Models.Errors.SDKError 4XX, 5XX */*

DeleteLogo

Delete the organization's logo.

Example Usage

using Clerk.BackendAPI;
using Clerk.BackendAPI.Models.Operations;
using Clerk.BackendAPI.Models.Components;

var sdk = new ClerkBackendApi(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

var res = await sdk.Organizations.DeleteLogoAsync(organizationId: "org_12345");

// handle response

Parameters

Parameter Type Required Description Example
OrganizationId string ✔️ The ID of the organization for which the logo will be deleted. org_12345

Response

DeleteOrganizationLogoResponse

Errors

Error Type Status Code Content Type
Clerk.BackendAPI.Models.Errors.ClerkErrors 404 application/json
Clerk.BackendAPI.Models.Errors.SDKError 4XX, 5XX */*