feat(backend): Introduce OrganizationRoleAPI (#2177)

.changeset/cold-comics-serve.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Add OrganizationRoleAPI for CRUD operations regarding instance level organization roles.

packages/backend/src/api/endpoints/OrganizationRoleApi.ts

@@ -0,0 +1,138 @@
+import { joinPaths } from '../../util/path';
+import type { DeletedObject, Role } from '../resources';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/organizations_roles';
+
+type GetRoleListParams = {
+ limit?: number;
+ offset?: number;
+ query?: string;
+ order_by?: string;
+};
+
+type CreateParams = {
+ /**
+ * A name of a role in a readable friendly format.
+ * F.e. `Teacher` or `Administrator`
+ */
+ name: string;
+
+ /**
+ * A unique identifier that represents the role.
+ * F.e. `org:administrator`
+ */
+ key: string;
+
+ /**
+ * A brief description of what the role represents or its intended use.
+ */
+ description: string;
+
+ /**
+ * An array of permission ids that will be assigned to this role.
+ */
+ permissions: string[];
+};
+
+type GetOrganizationRoleParams = { roleId: string };
+
+type UpdateParams = {
+ /**
+ * A name of a role in a readable friendly format.
+ * F.e. `Teacher` or `Administrator`
+ * Passing undefined has no effect to the existing value.
+ */
+ name?: string;
+
+ /**
+ * A unique identifier that represents the role.
+ * F.e. `org:administrator`
+ * Passing undefined has no effect to the existing value.
+ */
+ key?: string;
+
+ /**
+ * A brief description of what the role represents or its intended use.
+ * Passing undefined has no effect to the existing value.
+ */
+ description?: string;
+
+ /**
+ * An array of permission ids that will be assigned to this role.
+ * Passing undefined has no effect to the permission that already exist.
+ * Passing an empty array will override the existing permissions.
+ */
+ permissions?: string[];
+};
+
+type RemovePermissionParams = {
+ permissionId: string;
+ roleId: string;
+};
+
+type AssignPermissionParams = RemovePermissionParams;
+
+export class OrganizationRoleAPI extends AbstractAPI {
+ public async getOrganizationRoleList(params?: GetRoleListParams) {
+ return this.request<Role[]>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ });
+ }
+
+ public async createOrganizationRole(params: CreateParams) {
+ return this.request<Role>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ public async getOrganizationRole(params: GetOrganizationRoleParams) {
+ this.requireId(params.roleId);
+
+ return this.request<Role>({
+ method: 'GET',
+ path: joinPaths(basePath, params.roleId),
+ });
+ }
+
+ public async updateOrganizationRole(roleId: string, params: UpdateParams) {
+ this.requireId(roleId);
+ return this.request<Role>({
+ method: 'PATCH',
+ path: joinPaths(basePath, roleId),
+ bodyParams: params,
+ });
+ }
+
+ public async deleteOrganizationRole(roleId: string) {
+ this.requireId(roleId);
+ return this.request<DeletedObject>({
+ method: 'DELETE',
+ path: joinPaths(basePath, roleId),
+ });
+ }
+
+ public async assignPermissionToRole(params: AssignPermissionParams) {
+ const { roleId, permissionId } = params;
+ this.requireId(roleId);
+ this.requireId(permissionId);
+ return this.request<Role>({
+ method: 'POST',
+ path: joinPaths(basePath, roleId, 'permission', permissionId),
+ });
+ }
+
+ public async removePermissionFromRole(params: RemovePermissionParams) {
+ const { roleId, permissionId } = params;
+ this.requireId(roleId);
+ this.requireId(permissionId);
+ return this.request<Role>({
+ method: 'DELETE',
+ path: joinPaths(basePath, roleId, 'permission', permissionId),
+ });
+ }
+}

packages/backend/src/api/endpoints/index.ts

@@ -7,6 +7,7 @@ export * from './EmailApi';
 export * from './InterstitialApi';
 export * from './InvitationApi';
 export * from './OrganizationApi';
+export * from './OrganizationRoleApi';
 export * from './OrganizationPermissionApi';
 export * from './PhoneNumberApi';
 export * from './RedirectUrlApi';

packages/backend/src/api/factory.ts

@@ -8,6 +8,7 @@ import {
  InvitationAPI,
  OrganizationAPI,
  OrganizationPermissionAPI,
+ OrganizationRoleAPI,
  PhoneNumberAPI,
  RedirectUrlAPI,
  SessionAPI,
@@ -50,6 +51,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  interstitial: new InterstitialAPI(request),
  invitations: new InvitationAPI(request),
  organizations: new OrganizationAPI(request),
+ organizationRoles: new OrganizationRoleAPI(request),
  organizationPermissions: new OrganizationPermissionAPI(request),
  phoneNumbers: new PhoneNumberAPI(request),
  redirectUrls: new RedirectUrlAPI(request),

packages/backend/src/api/resources/JSON.ts

@@ -21,6 +21,7 @@ export enum ObjectType {
  Organization = 'organization',
  OrganizationInvitation = 'organization_invitation',
  OrganizationMembership = 'organization_membership',
+ Role = 'role',
  Permission = 'permission',
  PhoneNumber = 'phone_number',
  RedirectUrl = 'redirect_url',
@@ -186,6 +187,16 @@ export interface OrganizationMembershipPublicUserDataJSON {
  user_id: string;
 }
 
+export interface RoleJSON extends ClerkResourceJSON {
+ object: ObjectType.Role;
+ name: string;
+ key: string;
+ description: string;
+ permissions: PermissionJSON[];
+ created_at: number;
+ updated_at: number;
+}
+
 export interface PermissionJSON extends ClerkResourceJSON {
  object: ObjectType.Permission;
  id: string;

packages/backend/src/api/resources/Role.ts

@@ -0,0 +1,26 @@
+import type { RoleJSON } from './JSON';
+import { Permission } from './Permission';
+
+export class Role {
+ constructor(
+ readonly id: string,
+ readonly name: string,
+ readonly key: string,
+ readonly description: string,
+ readonly permissions: Permission[] = [],
+ readonly createdAt: number,
+ readonly updatedAt: number,
+ ) {}
+
+ static fromJSON(data: RoleJSON): Role {
+ return new Role(
+ data.id,
+ data.name,
+ data.key,
+ data.description,
+ (data.permissions || []).map(x => Permission.fromJSON(x)),
+ data.created_at,
+ data.updated_at,
+ );
+ }
+}

packages/backend/src/api/resources/index.ts

@@ -22,6 +22,7 @@ export * from './Invitation';
 export * from './JSON';
 export * from './OauthAccessToken';
 export * from './Organization';
+export * from './Role';
 export * from './Permission';
 export * from './OrganizationInvitation';
 export * from './OrganizationMembership';

packages/backend/src/exports.test.ts

@@ -27,6 +27,7 @@ export default (QUnit: QUnit) => {
  'Permission',
  'PhoneNumber',
  'RedirectUrl',
+ 'Role',
  'SMSMessage',
  'Session',
  'SignInToken',

packages/nextjs/src/api/__tests__/__snapshots__/exports.test.ts.snap

@@ -21,6 +21,7 @@ exports[`/api public exports should not include a breaking change 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",

packages/nextjs/src/edge-middleware/__tests__/__snapshots__/exports.test.ts.snap

@@ -21,6 +21,7 @@ exports[`/edge-middleware public exports should not include a breaking change 1`
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",

packages/nextjs/src/server/__tests__/__snapshots__/exports.test.ts.snap

@@ -32,6 +32,7 @@ exports[`/server public exports should not include a breaking change 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SECRET_KEY",
  "SIGN_IN_URL",
  "SIGN_UP_URL",

packages/sdk-node/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -23,6 +23,7 @@ exports[`module exports should not change unless explicitly set 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",
@@ -51,6 +52,7 @@ exports[`module exports should not change unless explicitly set 1`] = `
  "loadInterstitialFromLocal",
  "makeAuthObjectSerializable",
  "organizationPermissions",
+ "organizationRoles",
  "organizations",
  "phoneNumbers",
  "prunePrivateMetadata",

packages/sdk-node/src/index.ts

@@ -47,6 +47,7 @@ const {
  emails,
  invitations,
  organizations,
+ organizationRoles,
  organizationPermissions,
  clients,
  allowlistIdentifiers,
@@ -62,6 +63,7 @@ export {
  emails,
  invitations,
  organizations,
+ organizationRoles,
  organizationPermissions,
  clients,
  allowlistIdentifiers,

.changeset/cold-comics-serve.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Add OrganizationRoleAPI for CRUD operations regarding instance level organization roles.

packages/backend/src/api/endpoints/OrganizationRoleApi.ts

@@ -0,0 +1,138 @@
+import { joinPaths } from '../../util/path';
+import type { DeletedObject, Role } from '../resources';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/organizations_roles';
+
+type GetRoleListParams = {
+ limit?: number;
+ offset?: number;
+ query?: string;
+ order_by?: string;
+};
+
+type CreateParams = {
+ /**
+ * A name of a role in a readable friendly format.
+ * F.e. `Teacher` or `Administrator`
+ */
+ name: string;
+
+ /**
+ * A unique identifier that represents the role.
+ * F.e. `org:administrator`
+ */
+ key: string;
+
+ /**
+ * A brief description of what the role represents or its intended use.
+ */
+ description: string;
+
+ /**
+ * An array of permission ids that will be assigned to this role.
+ */
+ permissions: string[];
+};
+
+type GetOrganizationRoleParams = { roleId: string };
+
+type UpdateParams = {
+ /**
+ * A name of a role in a readable friendly format.
+ * F.e. `Teacher` or `Administrator`
+ * Passing undefined has no effect to the existing value.
+ */
+ name?: string;
+
+ /**
+ * A unique identifier that represents the role.
+ * F.e. `org:administrator`
+ * Passing undefined has no effect to the existing value.
+ */
+ key?: string;
+
+ /**
+ * A brief description of what the role represents or its intended use.
+ * Passing undefined has no effect to the existing value.
+ */
+ description?: string;
+
+ /**
+ * An array of permission ids that will be assigned to this role.
+ * Passing undefined has no effect to the permission that already exist.
+ * Passing an empty array will override the existing permissions.
+ */
+ permissions?: string[];
+};
+
+type RemovePermissionParams = {
+ permissionId: string;
+ roleId: string;
+};
+
+type AssignPermissionParams = RemovePermissionParams;
+
+export class OrganizationRoleAPI extends AbstractAPI {
+ public async getOrganizationRoleList(params?: GetRoleListParams) {
+ return this.request<Role[]>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ });
+ }
+
+ public async createOrganizationRole(params: CreateParams) {
+ return this.request<Role>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ public async getOrganizationRole(params: GetOrganizationRoleParams) {
+ this.requireId(params.roleId);
+
+ return this.request<Role>({
+ method: 'GET',
+ path: joinPaths(basePath, params.roleId),
+ });
+ }
+
+ public async updateOrganizationRole(roleId: string, params: UpdateParams) {
+ this.requireId(roleId);
+ return this.request<Role>({
+ method: 'PATCH',
+ path: joinPaths(basePath, roleId),
+ bodyParams: params,
+ });
+ }
+
+ public async deleteOrganizationRole(roleId: string) {
+ this.requireId(roleId);
+ return this.request<DeletedObject>({
+ method: 'DELETE',
+ path: joinPaths(basePath, roleId),
+ });
+ }
+
+ public async assignPermissionToRole(params: AssignPermissionParams) {
+ const { roleId, permissionId } = params;
+ this.requireId(roleId);
+ this.requireId(permissionId);
+ return this.request<Role>({
+ method: 'POST',
+ path: joinPaths(basePath, roleId, 'permission', permissionId),
+ });
+ }
+
+ public async removePermissionFromRole(params: RemovePermissionParams) {
+ const { roleId, permissionId } = params;
+ this.requireId(roleId);
+ this.requireId(permissionId);
+ return this.request<Role>({
+ method: 'DELETE',
+ path: joinPaths(basePath, roleId, 'permission', permissionId),
+ });
+ }
+}

packages/backend/src/api/endpoints/index.ts

@@ -7,6 +7,7 @@ export * from './EmailApi';
 export * from './InterstitialApi';
 export * from './InvitationApi';
 export * from './OrganizationApi';
+export * from './OrganizationRoleApi';
 export * from './OrganizationPermissionApi';
 export * from './PhoneNumberApi';
 export * from './RedirectUrlApi';

packages/backend/src/api/factory.ts

@@ -8,6 +8,7 @@ import {
  InvitationAPI,
  OrganizationAPI,
  OrganizationPermissionAPI,
+ OrganizationRoleAPI,
  PhoneNumberAPI,
  RedirectUrlAPI,
  SessionAPI,
@@ -50,6 +51,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  interstitial: new InterstitialAPI(request),
  invitations: new InvitationAPI(request),
  organizations: new OrganizationAPI(request),
+ organizationRoles: new OrganizationRoleAPI(request),
  organizationPermissions: new OrganizationPermissionAPI(request),
  phoneNumbers: new PhoneNumberAPI(request),
  redirectUrls: new RedirectUrlAPI(request),

packages/backend/src/api/resources/JSON.ts

@@ -21,6 +21,7 @@ export enum ObjectType {
  Organization = 'organization',
  OrganizationInvitation = 'organization_invitation',
  OrganizationMembership = 'organization_membership',
+ Role = 'role',
  Permission = 'permission',
  PhoneNumber = 'phone_number',
  RedirectUrl = 'redirect_url',
@@ -186,6 +187,16 @@ export interface OrganizationMembershipPublicUserDataJSON {
  user_id: string;
 }
 
+export interface RoleJSON extends ClerkResourceJSON {
+ object: ObjectType.Role;
+ name: string;
+ key: string;
+ description: string;
+ permissions: PermissionJSON[];
+ created_at: number;
+ updated_at: number;
+}
+
 export interface PermissionJSON extends ClerkResourceJSON {
  object: ObjectType.Permission;
  id: string;

packages/backend/src/api/resources/Role.ts

@@ -0,0 +1,26 @@
+import type { RoleJSON } from './JSON';
+import { Permission } from './Permission';
+
+export class Role {
+ constructor(
+ readonly id: string,
+ readonly name: string,
+ readonly key: string,
+ readonly description: string,
+ readonly permissions: Permission[] = [],
+ readonly createdAt: number,
+ readonly updatedAt: number,
+ ) {}
+
+ static fromJSON(data: RoleJSON): Role {
+ return new Role(
+ data.id,
+ data.name,
+ data.key,
+ data.description,
+ (data.permissions || []).map(x => Permission.fromJSON(x)),
+ data.created_at,
+ data.updated_at,
+ );
+ }
+}

packages/backend/src/api/resources/index.ts

@@ -22,6 +22,7 @@ export * from './Invitation';
 export * from './JSON';
 export * from './OauthAccessToken';
 export * from './Organization';
+export * from './Role';
 export * from './Permission';
 export * from './OrganizationInvitation';
 export * from './OrganizationMembership';

packages/backend/src/exports.test.ts

@@ -27,6 +27,7 @@ export default (QUnit: QUnit) => {
  'Permission',
  'PhoneNumber',
  'RedirectUrl',
+ 'Role',
  'SMSMessage',
  'Session',
  'SignInToken',

packages/nextjs/src/api/__tests__/__snapshots__/exports.test.ts.snap

@@ -21,6 +21,7 @@ exports[`/api public exports should not include a breaking change 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",

packages/nextjs/src/edge-middleware/__tests__/__snapshots__/exports.test.ts.snap

@@ -21,6 +21,7 @@ exports[`/edge-middleware public exports should not include a breaking change 1`
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",

packages/nextjs/src/server/__tests__/__snapshots__/exports.test.ts.snap

@@ -32,6 +32,7 @@ exports[`/server public exports should not include a breaking change 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SECRET_KEY",
  "SIGN_IN_URL",
  "SIGN_UP_URL",

packages/sdk-node/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -23,6 +23,7 @@ exports[`module exports should not change unless explicitly set 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",
@@ -51,6 +52,7 @@ exports[`module exports should not change unless explicitly set 1`] = `
  "loadInterstitialFromLocal",
  "makeAuthObjectSerializable",
  "organizationPermissions",
+ "organizationRoles",
  "organizations",
  "phoneNumbers",
  "prunePrivateMetadata",

packages/sdk-node/src/index.ts

@@ -47,6 +47,7 @@ const {
  emails,
  invitations,
  organizations,
+ organizationRoles,
  organizationPermissions,
  clients,
  allowlistIdentifiers,
@@ -62,6 +63,7 @@ export {
  emails,
  invitations,
  organizations,
+ organizationRoles,
  organizationPermissions,
  clients,
  allowlistIdentifiers,

.changeset/cold-comics-serve.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Add OrganizationRoleAPI for CRUD operations regarding instance level organization roles.

packages/backend/src/api/endpoints/OrganizationRoleApi.ts

@@ -0,0 +1,138 @@
+import { joinPaths } from '../../util/path';
+import type { DeletedObject, Role } from '../resources';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/organizations_roles';
+
+type GetRoleListParams = {
+ limit?: number;
+ offset?: number;
+ query?: string;
+ order_by?: string;
+};
+
+type CreateParams = {
+ /**
+ * A name of a role in a readable friendly format.
+ * F.e. `Teacher` or `Administrator`
+ */
+ name: string;
+
+ /**
+ * A unique identifier that represents the role.
+ * F.e. `org:administrator`
+ */
+ key: string;
+
+ /**
+ * A brief description of what the role represents or its intended use.
+ */
+ description: string;
+
+ /**
+ * An array of permission ids that will be assigned to this role.
+ */
+ permissions: string[];
+};
+
+type GetOrganizationRoleParams = { roleId: string };
+
+type UpdateParams = {
+ /**
+ * A name of a role in a readable friendly format.
+ * F.e. `Teacher` or `Administrator`
+ * Passing undefined has no effect to the existing value.
+ */
+ name?: string;
+
+ /**
+ * A unique identifier that represents the role.
+ * F.e. `org:administrator`
+ * Passing undefined has no effect to the existing value.
+ */
+ key?: string;
+
+ /**
+ * A brief description of what the role represents or its intended use.
+ * Passing undefined has no effect to the existing value.
+ */
+ description?: string;
+
+ /**
+ * An array of permission ids that will be assigned to this role.
+ * Passing undefined has no effect to the permission that already exist.
+ * Passing an empty array will override the existing permissions.
+ */
+ permissions?: string[];
+};
+
+type RemovePermissionParams = {
+ permissionId: string;
+ roleId: string;
+};
+
+type AssignPermissionParams = RemovePermissionParams;
+
+export class OrganizationRoleAPI extends AbstractAPI {
+ public async getOrganizationRoleList(params?: GetRoleListParams) {
+ return this.request<Role[]>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ });
+ }
+
+ public async createOrganizationRole(params: CreateParams) {
+ return this.request<Role>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ public async getOrganizationRole(params: GetOrganizationRoleParams) {
+ this.requireId(params.roleId);
+
+ return this.request<Role>({
+ method: 'GET',
+ path: joinPaths(basePath, params.roleId),
+ });
+ }
+
+ public async updateOrganizationRole(roleId: string, params: UpdateParams) {
+ this.requireId(roleId);
+ return this.request<Role>({
+ method: 'PATCH',
+ path: joinPaths(basePath, roleId),
+ bodyParams: params,
+ });
+ }
+
+ public async deleteOrganizationRole(roleId: string) {
+ this.requireId(roleId);
+ return this.request<DeletedObject>({
+ method: 'DELETE',
+ path: joinPaths(basePath, roleId),
+ });
+ }
+
+ public async assignPermissionToRole(params: AssignPermissionParams) {
+ const { roleId, permissionId } = params;
+ this.requireId(roleId);
+ this.requireId(permissionId);
+ return this.request<Role>({
+ method: 'POST',
+ path: joinPaths(basePath, roleId, 'permission', permissionId),
+ });
+ }
+
+ public async removePermissionFromRole(params: RemovePermissionParams) {
+ const { roleId, permissionId } = params;
+ this.requireId(roleId);
+ this.requireId(permissionId);
+ return this.request<Role>({
+ method: 'DELETE',
+ path: joinPaths(basePath, roleId, 'permission', permissionId),
+ });
+ }
+}

packages/backend/src/api/endpoints/index.ts

@@ -7,6 +7,7 @@ export * from './EmailApi';
 export * from './InterstitialApi';
 export * from './InvitationApi';
 export * from './OrganizationApi';
+export * from './OrganizationRoleApi';
 export * from './OrganizationPermissionApi';
 export * from './PhoneNumberApi';
 export * from './RedirectUrlApi';

packages/backend/src/api/factory.ts

@@ -8,6 +8,7 @@ import {
  InvitationAPI,
  OrganizationAPI,
  OrganizationPermissionAPI,
+ OrganizationRoleAPI,
  PhoneNumberAPI,
  RedirectUrlAPI,
  SessionAPI,
@@ -50,6 +51,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  interstitial: new InterstitialAPI(request),
  invitations: new InvitationAPI(request),
  organizations: new OrganizationAPI(request),
+ organizationRoles: new OrganizationRoleAPI(request),
  organizationPermissions: new OrganizationPermissionAPI(request),
  phoneNumbers: new PhoneNumberAPI(request),
  redirectUrls: new RedirectUrlAPI(request),

packages/backend/src/api/resources/JSON.ts

@@ -21,6 +21,7 @@ export enum ObjectType {
  Organization = 'organization',
  OrganizationInvitation = 'organization_invitation',
  OrganizationMembership = 'organization_membership',
+ Role = 'role',
  Permission = 'permission',
  PhoneNumber = 'phone_number',
  RedirectUrl = 'redirect_url',
@@ -186,6 +187,16 @@ export interface OrganizationMembershipPublicUserDataJSON {
  user_id: string;
 }
 
+export interface RoleJSON extends ClerkResourceJSON {
+ object: ObjectType.Role;
+ name: string;
+ key: string;
+ description: string;
+ permissions: PermissionJSON[];
+ created_at: number;
+ updated_at: number;
+}
+
 export interface PermissionJSON extends ClerkResourceJSON {
  object: ObjectType.Permission;
  id: string;

packages/backend/src/api/resources/Role.ts

@@ -0,0 +1,26 @@
+import type { RoleJSON } from './JSON';
+import { Permission } from './Permission';
+
+export class Role {
+ constructor(
+ readonly id: string,
+ readonly name: string,
+ readonly key: string,
+ readonly description: string,
+ readonly permissions: Permission[] = [],
+ readonly createdAt: number,
+ readonly updatedAt: number,
+ ) {}
+
+ static fromJSON(data: RoleJSON): Role {
+ return new Role(
+ data.id,
+ data.name,
+ data.key,
+ data.description,
+ (data.permissions || []).map(x => Permission.fromJSON(x)),
+ data.created_at,
+ data.updated_at,
+ );
+ }
+}

packages/backend/src/api/resources/index.ts

@@ -22,6 +22,7 @@ export * from './Invitation';
 export * from './JSON';
 export * from './OauthAccessToken';
 export * from './Organization';
+export * from './Role';
 export * from './Permission';
 export * from './OrganizationInvitation';
 export * from './OrganizationMembership';

packages/backend/src/exports.test.ts

@@ -27,6 +27,7 @@ export default (QUnit: QUnit) => {
  'Permission',
  'PhoneNumber',
  'RedirectUrl',
+ 'Role',
  'SMSMessage',
  'Session',
  'SignInToken',

packages/nextjs/src/api/__tests__/__snapshots__/exports.test.ts.snap

@@ -21,6 +21,7 @@ exports[`/api public exports should not include a breaking change 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",

packages/nextjs/src/edge-middleware/__tests__/__snapshots__/exports.test.ts.snap

@@ -21,6 +21,7 @@ exports[`/edge-middleware public exports should not include a breaking change 1`
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",

packages/nextjs/src/server/__tests__/__snapshots__/exports.test.ts.snap

@@ -32,6 +32,7 @@ exports[`/server public exports should not include a breaking change 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SECRET_KEY",
  "SIGN_IN_URL",
  "SIGN_UP_URL",

packages/sdk-node/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -23,6 +23,7 @@ exports[`module exports should not change unless explicitly set 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",
@@ -51,6 +52,7 @@ exports[`module exports should not change unless explicitly set 1`] = `
  "loadInterstitialFromLocal",
  "makeAuthObjectSerializable",
  "organizationPermissions",
+ "organizationRoles",
  "organizations",
  "phoneNumbers",
  "prunePrivateMetadata",

packages/sdk-node/src/index.ts

@@ -47,6 +47,7 @@ const {
  emails,
  invitations,
  organizations,
+ organizationRoles,
  organizationPermissions,
  clients,
  allowlistIdentifiers,
@@ -62,6 +63,7 @@ export {
  emails,
  invitations,
  organizations,
+ organizationRoles,
  organizationPermissions,
  clients,
  allowlistIdentifiers,

.changeset/cold-comics-serve.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Add OrganizationRoleAPI for CRUD operations regarding instance level organization roles.

packages/backend/src/api/endpoints/OrganizationRoleApi.ts

@@ -0,0 +1,138 @@
+import { joinPaths } from '../../util/path';
+import type { DeletedObject, Role } from '../resources';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/organizations_roles';
+
+type GetRoleListParams = {
+ limit?: number;
+ offset?: number;
+ query?: string;
+ order_by?: string;
+};
+
+type CreateParams = {
+ /**
+ * A name of a role in a readable friendly format.
+ * F.e. `Teacher` or `Administrator`
+ */
+ name: string;
+
+ /**
+ * A unique identifier that represents the role.
+ * F.e. `org:administrator`
+ */
+ key: string;
+
+ /**
+ * A brief description of what the role represents or its intended use.
+ */
+ description: string;
+
+ /**
+ * An array of permission ids that will be assigned to this role.
+ */
+ permissions: string[];
+};
+
+type GetOrganizationRoleParams = { roleId: string };
+
+type UpdateParams = {
+ /**
+ * A name of a role in a readable friendly format.
+ * F.e. `Teacher` or `Administrator`
+ * Passing undefined has no effect to the existing value.
+ */
+ name?: string;
+
+ /**
+ * A unique identifier that represents the role.
+ * F.e. `org:administrator`
+ * Passing undefined has no effect to the existing value.
+ */
+ key?: string;
+
+ /**
+ * A brief description of what the role represents or its intended use.
+ * Passing undefined has no effect to the existing value.
+ */
+ description?: string;
+
+ /**
+ * An array of permission ids that will be assigned to this role.
+ * Passing undefined has no effect to the permission that already exist.
+ * Passing an empty array will override the existing permissions.
+ */
+ permissions?: string[];
+};
+
+type RemovePermissionParams = {
+ permissionId: string;
+ roleId: string;
+};
+
+type AssignPermissionParams = RemovePermissionParams;
+
+export class OrganizationRoleAPI extends AbstractAPI {
+ public async getOrganizationRoleList(params?: GetRoleListParams) {
+ return this.request<Role[]>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ });
+ }
+
+ public async createOrganizationRole(params: CreateParams) {
+ return this.request<Role>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ public async getOrganizationRole(params: GetOrganizationRoleParams) {
+ this.requireId(params.roleId);
+
+ return this.request<Role>({
+ method: 'GET',
+ path: joinPaths(basePath, params.roleId),
+ });
+ }
+
+ public async updateOrganizationRole(roleId: string, params: UpdateParams) {
+ this.requireId(roleId);
+ return this.request<Role>({
+ method: 'PATCH',
+ path: joinPaths(basePath, roleId),
+ bodyParams: params,
+ });
+ }
+
+ public async deleteOrganizationRole(roleId: string) {
+ this.requireId(roleId);
+ return this.request<DeletedObject>({
+ method: 'DELETE',
+ path: joinPaths(basePath, roleId),
+ });
+ }
+
+ public async assignPermissionToRole(params: AssignPermissionParams) {
+ const { roleId, permissionId } = params;
+ this.requireId(roleId);
+ this.requireId(permissionId);
+ return this.request<Role>({
+ method: 'POST',
+ path: joinPaths(basePath, roleId, 'permission', permissionId),
+ });
+ }
+
+ public async removePermissionFromRole(params: RemovePermissionParams) {
+ const { roleId, permissionId } = params;
+ this.requireId(roleId);
+ this.requireId(permissionId);
+ return this.request<Role>({
+ method: 'DELETE',
+ path: joinPaths(basePath, roleId, 'permission', permissionId),
+ });
+ }
+}

packages/backend/src/api/endpoints/index.ts

@@ -7,6 +7,7 @@ export * from './EmailApi';
 export * from './InterstitialApi';
 export * from './InvitationApi';
 export * from './OrganizationApi';
+export * from './OrganizationRoleApi';
 export * from './OrganizationPermissionApi';
 export * from './PhoneNumberApi';
 export * from './RedirectUrlApi';

packages/backend/src/api/factory.ts

@@ -8,6 +8,7 @@ import {
  InvitationAPI,
  OrganizationAPI,
  OrganizationPermissionAPI,
+ OrganizationRoleAPI,
  PhoneNumberAPI,
  RedirectUrlAPI,
  SessionAPI,
@@ -50,6 +51,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  interstitial: new InterstitialAPI(request),
  invitations: new InvitationAPI(request),
  organizations: new OrganizationAPI(request),
+ organizationRoles: new OrganizationRoleAPI(request),
  organizationPermissions: new OrganizationPermissionAPI(request),
  phoneNumbers: new PhoneNumberAPI(request),
  redirectUrls: new RedirectUrlAPI(request),

packages/backend/src/api/resources/JSON.ts

@@ -21,6 +21,7 @@ export enum ObjectType {
  Organization = 'organization',
  OrganizationInvitation = 'organization_invitation',
  OrganizationMembership = 'organization_membership',
+ Role = 'role',
  Permission = 'permission',
  PhoneNumber = 'phone_number',
  RedirectUrl = 'redirect_url',
@@ -186,6 +187,16 @@ export interface OrganizationMembershipPublicUserDataJSON {
  user_id: string;
 }
 
+export interface RoleJSON extends ClerkResourceJSON {
+ object: ObjectType.Role;
+ name: string;
+ key: string;
+ description: string;
+ permissions: PermissionJSON[];
+ created_at: number;
+ updated_at: number;
+}
+
 export interface PermissionJSON extends ClerkResourceJSON {
  object: ObjectType.Permission;
  id: string;

packages/backend/src/api/resources/Role.ts

@@ -0,0 +1,26 @@
+import type { RoleJSON } from './JSON';
+import { Permission } from './Permission';
+
+export class Role {
+ constructor(
+ readonly id: string,
+ readonly name: string,
+ readonly key: string,
+ readonly description: string,
+ readonly permissions: Permission[] = [],
+ readonly createdAt: number,
+ readonly updatedAt: number,
+ ) {}
+
+ static fromJSON(data: RoleJSON): Role {
+ return new Role(
+ data.id,
+ data.name,
+ data.key,
+ data.description,
+ (data.permissions || []).map(x => Permission.fromJSON(x)),
+ data.created_at,
+ data.updated_at,
+ );
+ }
+}

packages/backend/src/api/resources/index.ts

@@ -22,6 +22,7 @@ export * from './Invitation';
 export * from './JSON';
 export * from './OauthAccessToken';
 export * from './Organization';
+export * from './Role';
 export * from './Permission';
 export * from './OrganizationInvitation';
 export * from './OrganizationMembership';

packages/backend/src/exports.test.ts

@@ -27,6 +27,7 @@ export default (QUnit: QUnit) => {
  'Permission',
  'PhoneNumber',
  'RedirectUrl',
+ 'Role',
  'SMSMessage',
  'Session',
  'SignInToken',

packages/nextjs/src/api/__tests__/__snapshots__/exports.test.ts.snap

@@ -21,6 +21,7 @@ exports[`/api public exports should not include a breaking change 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",

packages/nextjs/src/edge-middleware/__tests__/__snapshots__/exports.test.ts.snap

@@ -21,6 +21,7 @@ exports[`/edge-middleware public exports should not include a breaking change 1`
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",

packages/nextjs/src/server/__tests__/__snapshots__/exports.test.ts.snap

@@ -32,6 +32,7 @@ exports[`/server public exports should not include a breaking change 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SECRET_KEY",
  "SIGN_IN_URL",
  "SIGN_UP_URL",

packages/sdk-node/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -23,6 +23,7 @@ exports[`module exports should not change unless explicitly set 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",
@@ -51,6 +52,7 @@ exports[`module exports should not change unless explicitly set 1`] = `
  "loadInterstitialFromLocal",
  "makeAuthObjectSerializable",
  "organizationPermissions",
+ "organizationRoles",
  "organizations",
  "phoneNumbers",
  "prunePrivateMetadata",

packages/sdk-node/src/index.ts

@@ -47,6 +47,7 @@ const {
  emails,
  invitations,
  organizations,
+ organizationRoles,
  organizationPermissions,
  clients,
  allowlistIdentifiers,
@@ -62,6 +63,7 @@ export {
  emails,
  invitations,
  organizations,
+ organizationRoles,
  organizationPermissions,
  clients,
  allowlistIdentifiers,

.changeset/cold-comics-serve.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Add OrganizationRoleAPI for CRUD operations regarding instance level organization roles.

packages/backend/src/api/endpoints/OrganizationRoleApi.ts

@@ -0,0 +1,138 @@
+import { joinPaths } from '../../util/path';
+import type { DeletedObject, Role } from '../resources';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/organizations_roles';
+
+type GetRoleListParams = {
+ limit?: number;
+ offset?: number;
+ query?: string;
+ order_by?: string;
+};
+
+type CreateParams = {
+ /**
+ * A name of a role in a readable friendly format.
+ * F.e. `Teacher` or `Administrator`
+ */
+ name: string;
+
+ /**
+ * A unique identifier that represents the role.
+ * F.e. `org:administrator`
+ */
+ key: string;
+
+ /**
+ * A brief description of what the role represents or its intended use.
+ */
+ description: string;
+
+ /**
+ * An array of permission ids that will be assigned to this role.
+ */
+ permissions: string[];
+};
+
+type GetOrganizationRoleParams = { roleId: string };
+
+type UpdateParams = {
+ /**
+ * A name of a role in a readable friendly format.
+ * F.e. `Teacher` or `Administrator`
+ * Passing undefined has no effect to the existing value.
+ */
+ name?: string;
+
+ /**
+ * A unique identifier that represents the role.
+ * F.e. `org:administrator`
+ * Passing undefined has no effect to the existing value.
+ */
+ key?: string;
+
+ /**
+ * A brief description of what the role represents or its intended use.
+ * Passing undefined has no effect to the existing value.
+ */
+ description?: string;
+
+ /**
+ * An array of permission ids that will be assigned to this role.
+ * Passing undefined has no effect to the permission that already exist.
+ * Passing an empty array will override the existing permissions.
+ */
+ permissions?: string[];
+};
+
+type RemovePermissionParams = {
+ permissionId: string;
+ roleId: string;
+};
+
+type AssignPermissionParams = RemovePermissionParams;
+
+export class OrganizationRoleAPI extends AbstractAPI {
+ public async getOrganizationRoleList(params?: GetRoleListParams) {
+ return this.request<Role[]>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ });
+ }
+
+ public async createOrganizationRole(params: CreateParams) {
+ return this.request<Role>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ public async getOrganizationRole(params: GetOrganizationRoleParams) {
+ this.requireId(params.roleId);
+
+ return this.request<Role>({
+ method: 'GET',
+ path: joinPaths(basePath, params.roleId),
+ });
+ }
+
+ public async updateOrganizationRole(roleId: string, params: UpdateParams) {
+ this.requireId(roleId);
+ return this.request<Role>({
+ method: 'PATCH',
+ path: joinPaths(basePath, roleId),
+ bodyParams: params,
+ });
+ }
+
+ public async deleteOrganizationRole(roleId: string) {
+ this.requireId(roleId);
+ return this.request<DeletedObject>({
+ method: 'DELETE',
+ path: joinPaths(basePath, roleId),
+ });
+ }
+
+ public async assignPermissionToRole(params: AssignPermissionParams) {
+ const { roleId, permissionId } = params;
+ this.requireId(roleId);
+ this.requireId(permissionId);
+ return this.request<Role>({
+ method: 'POST',
+ path: joinPaths(basePath, roleId, 'permission', permissionId),
+ });
+ }
+
+ public async removePermissionFromRole(params: RemovePermissionParams) {
+ const { roleId, permissionId } = params;
+ this.requireId(roleId);
+ this.requireId(permissionId);
+ return this.request<Role>({
+ method: 'DELETE',
+ path: joinPaths(basePath, roleId, 'permission', permissionId),
+ });
+ }
+}

packages/backend/src/api/endpoints/index.ts

@@ -7,6 +7,7 @@ export * from './EmailApi';
 export * from './InterstitialApi';
 export * from './InvitationApi';
 export * from './OrganizationApi';
+export * from './OrganizationRoleApi';
 export * from './OrganizationPermissionApi';
 export * from './PhoneNumberApi';
 export * from './RedirectUrlApi';

packages/backend/src/api/factory.ts

@@ -8,6 +8,7 @@ import {
  InvitationAPI,
  OrganizationAPI,
  OrganizationPermissionAPI,
+ OrganizationRoleAPI,
  PhoneNumberAPI,
  RedirectUrlAPI,
  SessionAPI,
@@ -50,6 +51,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  interstitial: new InterstitialAPI(request),
  invitations: new InvitationAPI(request),
  organizations: new OrganizationAPI(request),
+ organizationRoles: new OrganizationRoleAPI(request),
  organizationPermissions: new OrganizationPermissionAPI(request),
  phoneNumbers: new PhoneNumberAPI(request),
  redirectUrls: new RedirectUrlAPI(request),

packages/backend/src/api/resources/JSON.ts

@@ -21,6 +21,7 @@ export enum ObjectType {
  Organization = 'organization',
  OrganizationInvitation = 'organization_invitation',
  OrganizationMembership = 'organization_membership',
+ Role = 'role',
  Permission = 'permission',
  PhoneNumber = 'phone_number',
  RedirectUrl = 'redirect_url',
@@ -186,6 +187,16 @@ export interface OrganizationMembershipPublicUserDataJSON {
  user_id: string;
 }
 
+export interface RoleJSON extends ClerkResourceJSON {
+ object: ObjectType.Role;
+ name: string;
+ key: string;
+ description: string;
+ permissions: PermissionJSON[];
+ created_at: number;
+ updated_at: number;
+}
+
 export interface PermissionJSON extends ClerkResourceJSON {
  object: ObjectType.Permission;
  id: string;

packages/backend/src/api/resources/Role.ts

@@ -0,0 +1,26 @@
+import type { RoleJSON } from './JSON';
+import { Permission } from './Permission';
+
+export class Role {
+ constructor(
+ readonly id: string,
+ readonly name: string,
+ readonly key: string,
+ readonly description: string,
+ readonly permissions: Permission[] = [],
+ readonly createdAt: number,
+ readonly updatedAt: number,
+ ) {}
+
+ static fromJSON(data: RoleJSON): Role {
+ return new Role(
+ data.id,
+ data.name,
+ data.key,
+ data.description,
+ (data.permissions || []).map(x => Permission.fromJSON(x)),
+ data.created_at,
+ data.updated_at,
+ );
+ }
+}

packages/backend/src/api/resources/index.ts

@@ -22,6 +22,7 @@ export * from './Invitation';
 export * from './JSON';
 export * from './OauthAccessToken';
 export * from './Organization';
+export * from './Role';
 export * from './Permission';
 export * from './OrganizationInvitation';
 export * from './OrganizationMembership';

packages/backend/src/exports.test.ts

@@ -27,6 +27,7 @@ export default (QUnit: QUnit) => {
  'Permission',
  'PhoneNumber',
  'RedirectUrl',
+ 'Role',
  'SMSMessage',
  'Session',
  'SignInToken',

packages/nextjs/src/api/__tests__/__snapshots__/exports.test.ts.snap

@@ -21,6 +21,7 @@ exports[`/api public exports should not include a breaking change 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",

packages/nextjs/src/edge-middleware/__tests__/__snapshots__/exports.test.ts.snap

@@ -21,6 +21,7 @@ exports[`/edge-middleware public exports should not include a breaking change 1`
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",

packages/nextjs/src/server/__tests__/__snapshots__/exports.test.ts.snap

@@ -32,6 +32,7 @@ exports[`/server public exports should not include a breaking change 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SECRET_KEY",
  "SIGN_IN_URL",
  "SIGN_UP_URL",

packages/sdk-node/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -23,6 +23,7 @@ exports[`module exports should not change unless explicitly set 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",
@@ -51,6 +52,7 @@ exports[`module exports should not change unless explicitly set 1`] = `
  "loadInterstitialFromLocal",
  "makeAuthObjectSerializable",
  "organizationPermissions",
+ "organizationRoles",
  "organizations",
  "phoneNumbers",
  "prunePrivateMetadata",

packages/sdk-node/src/index.ts

@@ -47,6 +47,7 @@ const {
  emails,
  invitations,
  organizations,
+ organizationRoles,
  organizationPermissions,
  clients,
  allowlistIdentifiers,
@@ -62,6 +63,7 @@ export {
  emails,
  invitations,
  organizations,
+ organizationRoles,
  organizationPermissions,
  clients,
  allowlistIdentifiers,

.changeset/cold-comics-serve.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Add OrganizationRoleAPI for CRUD operations regarding instance level organization roles.

packages/backend/src/api/endpoints/OrganizationRoleApi.ts

@@ -0,0 +1,138 @@
+import { joinPaths } from '../../util/path';
+import type { DeletedObject, Role } from '../resources';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/organizations_roles';
+
+type GetRoleListParams = {
+ limit?: number;
+ offset?: number;
+ query?: string;
+ order_by?: string;
+};
+
+type CreateParams = {
+ /**
+ * A name of a role in a readable friendly format.
+ * F.e. `Teacher` or `Administrator`
+ */
+ name: string;
+
+ /**
+ * A unique identifier that represents the role.
+ * F.e. `org:administrator`
+ */
+ key: string;
+
+ /**
+ * A brief description of what the role represents or its intended use.
+ */
+ description: string;
+
+ /**
+ * An array of permission ids that will be assigned to this role.
+ */
+ permissions: string[];
+};
+
+type GetOrganizationRoleParams = { roleId: string };
+
+type UpdateParams = {
+ /**
+ * A name of a role in a readable friendly format.
+ * F.e. `Teacher` or `Administrator`
+ * Passing undefined has no effect to the existing value.
+ */
+ name?: string;
+
+ /**
+ * A unique identifier that represents the role.
+ * F.e. `org:administrator`
+ * Passing undefined has no effect to the existing value.
+ */
+ key?: string;
+
+ /**
+ * A brief description of what the role represents or its intended use.
+ * Passing undefined has no effect to the existing value.
+ */
+ description?: string;
+
+ /**
+ * An array of permission ids that will be assigned to this role.
+ * Passing undefined has no effect to the permission that already exist.
+ * Passing an empty array will override the existing permissions.
+ */
+ permissions?: string[];
+};
+
+type RemovePermissionParams = {
+ permissionId: string;
+ roleId: string;
+};
+
+type AssignPermissionParams = RemovePermissionParams;
+
+export class OrganizationRoleAPI extends AbstractAPI {
+ public async getOrganizationRoleList(params?: GetRoleListParams) {
+ return this.request<Role[]>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ });
+ }
+
+ public async createOrganizationRole(params: CreateParams) {
+ return this.request<Role>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ public async getOrganizationRole(params: GetOrganizationRoleParams) {
+ this.requireId(params.roleId);
+
+ return this.request<Role>({
+ method: 'GET',
+ path: joinPaths(basePath, params.roleId),
+ });
+ }
+
+ public async updateOrganizationRole(roleId: string, params: UpdateParams) {
+ this.requireId(roleId);
+ return this.request<Role>({
+ method: 'PATCH',
+ path: joinPaths(basePath, roleId),
+ bodyParams: params,
+ });
+ }
+
+ public async deleteOrganizationRole(roleId: string) {
+ this.requireId(roleId);
+ return this.request<DeletedObject>({
+ method: 'DELETE',
+ path: joinPaths(basePath, roleId),
+ });
+ }
+
+ public async assignPermissionToRole(params: AssignPermissionParams) {
+ const { roleId, permissionId } = params;
+ this.requireId(roleId);
+ this.requireId(permissionId);
+ return this.request<Role>({
+ method: 'POST',
+ path: joinPaths(basePath, roleId, 'permission', permissionId),
+ });
+ }
+
+ public async removePermissionFromRole(params: RemovePermissionParams) {
+ const { roleId, permissionId } = params;
+ this.requireId(roleId);
+ this.requireId(permissionId);
+ return this.request<Role>({
+ method: 'DELETE',
+ path: joinPaths(basePath, roleId, 'permission', permissionId),
+ });
+ }
+}

packages/backend/src/api/endpoints/index.ts

@@ -7,6 +7,7 @@ export * from './EmailApi';
 export * from './InterstitialApi';
 export * from './InvitationApi';
 export * from './OrganizationApi';
+export * from './OrganizationRoleApi';
 export * from './OrganizationPermissionApi';
 export * from './PhoneNumberApi';
 export * from './RedirectUrlApi';

packages/backend/src/api/factory.ts

@@ -8,6 +8,7 @@ import {
  InvitationAPI,
  OrganizationAPI,
  OrganizationPermissionAPI,
+ OrganizationRoleAPI,
  PhoneNumberAPI,
  RedirectUrlAPI,
  SessionAPI,
@@ -50,6 +51,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  interstitial: new InterstitialAPI(request),
  invitations: new InvitationAPI(request),
  organizations: new OrganizationAPI(request),
+ organizationRoles: new OrganizationRoleAPI(request),
  organizationPermissions: new OrganizationPermissionAPI(request),
  phoneNumbers: new PhoneNumberAPI(request),
  redirectUrls: new RedirectUrlAPI(request),

packages/backend/src/api/resources/JSON.ts

@@ -21,6 +21,7 @@ export enum ObjectType {
  Organization = 'organization',
  OrganizationInvitation = 'organization_invitation',
  OrganizationMembership = 'organization_membership',
+ Role = 'role',
  Permission = 'permission',
  PhoneNumber = 'phone_number',
  RedirectUrl = 'redirect_url',
@@ -186,6 +187,16 @@ export interface OrganizationMembershipPublicUserDataJSON {
  user_id: string;
 }
 
+export interface RoleJSON extends ClerkResourceJSON {
+ object: ObjectType.Role;
+ name: string;
+ key: string;
+ description: string;
+ permissions: PermissionJSON[];
+ created_at: number;
+ updated_at: number;
+}
+
 export interface PermissionJSON extends ClerkResourceJSON {
  object: ObjectType.Permission;
  id: string;

packages/backend/src/api/resources/Role.ts

@@ -0,0 +1,26 @@
+import type { RoleJSON } from './JSON';
+import { Permission } from './Permission';
+
+export class Role {
+ constructor(
+ readonly id: string,
+ readonly name: string,
+ readonly key: string,
+ readonly description: string,
+ readonly permissions: Permission[] = [],
+ readonly createdAt: number,
+ readonly updatedAt: number,
+ ) {}
+
+ static fromJSON(data: RoleJSON): Role {
+ return new Role(
+ data.id,
+ data.name,
+ data.key,
+ data.description,
+ (data.permissions || []).map(x => Permission.fromJSON(x)),
+ data.created_at,
+ data.updated_at,
+ );
+ }
+}

packages/backend/src/api/resources/index.ts

@@ -22,6 +22,7 @@ export * from './Invitation';
 export * from './JSON';
 export * from './OauthAccessToken';
 export * from './Organization';
+export * from './Role';
 export * from './Permission';
 export * from './OrganizationInvitation';
 export * from './OrganizationMembership';

packages/backend/src/exports.test.ts

@@ -27,6 +27,7 @@ export default (QUnit: QUnit) => {
  'Permission',
  'PhoneNumber',
  'RedirectUrl',
+ 'Role',
  'SMSMessage',
  'Session',
  'SignInToken',

packages/nextjs/src/api/__tests__/__snapshots__/exports.test.ts.snap

@@ -21,6 +21,7 @@ exports[`/api public exports should not include a breaking change 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",

packages/nextjs/src/edge-middleware/__tests__/__snapshots__/exports.test.ts.snap

@@ -21,6 +21,7 @@ exports[`/edge-middleware public exports should not include a breaking change 1`
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",

packages/nextjs/src/server/__tests__/__snapshots__/exports.test.ts.snap

@@ -32,6 +32,7 @@ exports[`/server public exports should not include a breaking change 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SECRET_KEY",
  "SIGN_IN_URL",
  "SIGN_UP_URL",

packages/sdk-node/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -23,6 +23,7 @@ exports[`module exports should not change unless explicitly set 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",
@@ -51,6 +52,7 @@ exports[`module exports should not change unless explicitly set 1`] = `
  "loadInterstitialFromLocal",
  "makeAuthObjectSerializable",
  "organizationPermissions",
+ "organizationRoles",
  "organizations",
  "phoneNumbers",
  "prunePrivateMetadata",

packages/sdk-node/src/index.ts

@@ -47,6 +47,7 @@ const {
  emails,
  invitations,
  organizations,
+ organizationRoles,
  organizationPermissions,
  clients,
  allowlistIdentifiers,
@@ -62,6 +63,7 @@ export {
  emails,
  invitations,
  organizations,
+ organizationRoles,
  organizationPermissions,
  clients,
  allowlistIdentifiers,

.changeset/cold-comics-serve.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Add OrganizationRoleAPI for CRUD operations regarding instance level organization roles.

packages/backend/src/api/endpoints/OrganizationRoleApi.ts

@@ -0,0 +1,138 @@
+import { joinPaths } from '../../util/path';
+import type { DeletedObject, Role } from '../resources';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/organizations_roles';
+
+type GetRoleListParams = {
+ limit?: number;
+ offset?: number;
+ query?: string;
+ order_by?: string;
+};
+
+type CreateParams = {
+ /**
+ * A name of a role in a readable friendly format.
+ * F.e. `Teacher` or `Administrator`
+ */
+ name: string;
+
+ /**
+ * A unique identifier that represents the role.
+ * F.e. `org:administrator`
+ */
+ key: string;
+
+ /**
+ * A brief description of what the role represents or its intended use.
+ */
+ description: string;
+
+ /**
+ * An array of permission ids that will be assigned to this role.
+ */
+ permissions: string[];
+};
+
+type GetOrganizationRoleParams = { roleId: string };
+
+type UpdateParams = {
+ /**
+ * A name of a role in a readable friendly format.
+ * F.e. `Teacher` or `Administrator`
+ * Passing undefined has no effect to the existing value.
+ */
+ name?: string;
+
+ /**
+ * A unique identifier that represents the role.
+ * F.e. `org:administrator`
+ * Passing undefined has no effect to the existing value.
+ */
+ key?: string;
+
+ /**
+ * A brief description of what the role represents or its intended use.
+ * Passing undefined has no effect to the existing value.
+ */
+ description?: string;
+
+ /**
+ * An array of permission ids that will be assigned to this role.
+ * Passing undefined has no effect to the permission that already exist.
+ * Passing an empty array will override the existing permissions.
+ */
+ permissions?: string[];
+};
+
+type RemovePermissionParams = {
+ permissionId: string;
+ roleId: string;
+};
+
+type AssignPermissionParams = RemovePermissionParams;
+
+export class OrganizationRoleAPI extends AbstractAPI {
+ public async getOrganizationRoleList(params?: GetRoleListParams) {
+ return this.request<Role[]>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ });
+ }
+
+ public async createOrganizationRole(params: CreateParams) {
+ return this.request<Role>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ public async getOrganizationRole(params: GetOrganizationRoleParams) {
+ this.requireId(params.roleId);
+
+ return this.request<Role>({
+ method: 'GET',
+ path: joinPaths(basePath, params.roleId),
+ });
+ }
+
+ public async updateOrganizationRole(roleId: string, params: UpdateParams) {
+ this.requireId(roleId);
+ return this.request<Role>({
+ method: 'PATCH',
+ path: joinPaths(basePath, roleId),
+ bodyParams: params,
+ });
+ }
+
+ public async deleteOrganizationRole(roleId: string) {
+ this.requireId(roleId);
+ return this.request<DeletedObject>({
+ method: 'DELETE',
+ path: joinPaths(basePath, roleId),
+ });
+ }
+
+ public async assignPermissionToRole(params: AssignPermissionParams) {
+ const { roleId, permissionId } = params;
+ this.requireId(roleId);
+ this.requireId(permissionId);
+ return this.request<Role>({
+ method: 'POST',
+ path: joinPaths(basePath, roleId, 'permission', permissionId),
+ });
+ }
+
+ public async removePermissionFromRole(params: RemovePermissionParams) {
+ const { roleId, permissionId } = params;
+ this.requireId(roleId);
+ this.requireId(permissionId);
+ return this.request<Role>({
+ method: 'DELETE',
+ path: joinPaths(basePath, roleId, 'permission', permissionId),
+ });
+ }
+}

packages/backend/src/api/endpoints/index.ts

@@ -7,6 +7,7 @@ export * from './EmailApi';
 export * from './InterstitialApi';
 export * from './InvitationApi';
 export * from './OrganizationApi';
+export * from './OrganizationRoleApi';
 export * from './OrganizationPermissionApi';
 export * from './PhoneNumberApi';
 export * from './RedirectUrlApi';

packages/backend/src/api/factory.ts

@@ -8,6 +8,7 @@ import {
  InvitationAPI,
  OrganizationAPI,
  OrganizationPermissionAPI,
+ OrganizationRoleAPI,
  PhoneNumberAPI,
  RedirectUrlAPI,
  SessionAPI,
@@ -50,6 +51,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  interstitial: new InterstitialAPI(request),
  invitations: new InvitationAPI(request),
  organizations: new OrganizationAPI(request),
+ organizationRoles: new OrganizationRoleAPI(request),
  organizationPermissions: new OrganizationPermissionAPI(request),
  phoneNumbers: new PhoneNumberAPI(request),
  redirectUrls: new RedirectUrlAPI(request),

packages/backend/src/api/resources/JSON.ts

@@ -21,6 +21,7 @@ export enum ObjectType {
  Organization = 'organization',
  OrganizationInvitation = 'organization_invitation',
  OrganizationMembership = 'organization_membership',
+ Role = 'role',
  Permission = 'permission',
  PhoneNumber = 'phone_number',
  RedirectUrl = 'redirect_url',
@@ -186,6 +187,16 @@ export interface OrganizationMembershipPublicUserDataJSON {
  user_id: string;
 }
 
+export interface RoleJSON extends ClerkResourceJSON {
+ object: ObjectType.Role;
+ name: string;
+ key: string;
+ description: string;
+ permissions: PermissionJSON[];
+ created_at: number;
+ updated_at: number;
+}
+
 export interface PermissionJSON extends ClerkResourceJSON {
  object: ObjectType.Permission;
  id: string;

packages/backend/src/api/resources/Role.ts

@@ -0,0 +1,26 @@
+import type { RoleJSON } from './JSON';
+import { Permission } from './Permission';
+
+export class Role {
+ constructor(
+ readonly id: string,
+ readonly name: string,
+ readonly key: string,
+ readonly description: string,
+ readonly permissions: Permission[] = [],
+ readonly createdAt: number,
+ readonly updatedAt: number,
+ ) {}
+
+ static fromJSON(data: RoleJSON): Role {
+ return new Role(
+ data.id,
+ data.name,
+ data.key,
+ data.description,
+ (data.permissions || []).map(x => Permission.fromJSON(x)),
+ data.created_at,
+ data.updated_at,
+ );
+ }
+}

packages/backend/src/api/resources/index.ts

@@ -22,6 +22,7 @@ export * from './Invitation';
 export * from './JSON';
 export * from './OauthAccessToken';
 export * from './Organization';
+export * from './Role';
 export * from './Permission';
 export * from './OrganizationInvitation';
 export * from './OrganizationMembership';

packages/backend/src/exports.test.ts

@@ -27,6 +27,7 @@ export default (QUnit: QUnit) => {
  'Permission',
  'PhoneNumber',
  'RedirectUrl',
+ 'Role',
  'SMSMessage',
  'Session',
  'SignInToken',

packages/nextjs/src/api/__tests__/__snapshots__/exports.test.ts.snap

@@ -21,6 +21,7 @@ exports[`/api public exports should not include a breaking change 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",

packages/nextjs/src/edge-middleware/__tests__/__snapshots__/exports.test.ts.snap

@@ -21,6 +21,7 @@ exports[`/edge-middleware public exports should not include a breaking change 1`
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",

packages/nextjs/src/server/__tests__/__snapshots__/exports.test.ts.snap

@@ -32,6 +32,7 @@ exports[`/server public exports should not include a breaking change 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SECRET_KEY",
  "SIGN_IN_URL",
  "SIGN_UP_URL",

packages/sdk-node/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -23,6 +23,7 @@ exports[`module exports should not change unless explicitly set 1`] = `
  "Permission",
  "PhoneNumber",
  "RedirectUrl",
+ "Role",
  "SMSMessage",
  "Session",
  "SignInToken",
@@ -51,6 +52,7 @@ exports[`module exports should not change unless explicitly set 1`] = `
  "loadInterstitialFromLocal",
  "makeAuthObjectSerializable",
  "organizationPermissions",
+ "organizationRoles",
  "organizations",
  "phoneNumbers",
  "prunePrivateMetadata",

packages/sdk-node/src/index.ts

@@ -47,6 +47,7 @@ const {
  emails,
  invitations,
  organizations,
+ organizationRoles,
  organizationPermissions,
  clients,
  allowlistIdentifiers,
@@ -62,6 +63,7 @@ export {
  emails,
  invitations,
  organizations,
+ organizationRoles,
  organizationPermissions,
  clients,
  allowlistIdentifiers,