Override Clerk interfaces with custom types

Clerk provides TypeScript interfaces that you can use to define custom types for your application. Custom types provide auto-complete and prevent TypeScript errors. You can define custom types for the following:

• ClerkAuthorization
• CustomJwtSessionClaims
• OrganizationPublicMetadata
• OrganizationInvitationPublicMetadata
• OrganizationMembershipPublicMetadata
• SignUpUnsafeMetadata
• UserPublicMetadata
• UserPrivateMetadata
• UserUnsafeMetadata

Example: custom JWT claims

To override an interface, you must define a global type, as shown in the following example:

1. In your application's root folder, add a types directory.
2. Inside of the types directory, add a globals.d.ts file.
3. Create the CustomJwtSessionClaims interface and declare it globally.
4. Add the custom claims to the CustomJwtSessionClaims interface.

export {}

declare global {
  interface CustomJwtSessionClaims {
    firstName?: string
    primaryEmail?: string
    metadata: {
      onboardingComplete?: boolean
    }
  }
}

Example: custom Roles and Permissions

When defining custom types for Roles and Permissions:

• Custom Permissions are merged with System Permissions
• Custom Roles completely replace default Roles (org:admin and org:member)

export {}

declare global {
  interface ClerkAuthorization {
    permission: 'org:quiz:create' | 'org:quiz:grade' | 'org:quiz:read' | 'org:quiz:fill'
    role: 'org:super_admin' | 'org:teacher' | 'org:student'
  }
}