Models

This page documents the data structures used throughout the NextJS SDK.

User

The User model represents an authenticated user in the system.

interface User {
  id: string
  email: string
  emailVerified: boolean
  createdAt: string // ISO 8601 datetime
  updatedAt: string // ISO 8601 datetime
  version: number
  // Frontend specific fields
  name?: string
  avatar?: string
  preferences?: UserPreferences
}

interface UserPreferences {
  theme?: 'light' | 'dark' | 'system'
  language?: string
  notifications?: {
    email?: boolean
    push?: boolean
  }
}

User Properties

• id: Unique identifier for the user
• email: User's email address, used for authentication and communication
• emailVerified: Indicates whether the user's email has been verified
• createdAt: Timestamp when the user account was created
• updatedAt: Timestamp of the last update to the user account
• version: Version number for optimistic concurrency control
• name: Optional display name for the user
• avatar: Optional URL to the user's profile picture
• preferences: User-specific settings and preferences

UserPreferences Properties

• theme: User's preferred UI theme
• language: User's preferred language
• notifications: User's notification preferences
  • email: Whether to receive email notifications
  • push: Whether to receive push notifications

Organization

The Organization model represents a group of users working together.

interface Organization {
  id: string
  name: string
  createdBy: string // UserId
  createdAt: string // ISO 8601 datetime
  updatedAt: string // ISO 8601 datetime
  version: number
  // Frontend specific fields
  slug?: string
  settings?: OrganizationSettings
}

interface OrganizationSettings {
  allowedDomains?: string[]
  requireDomainMatch?: boolean
  defaultRole?: string
}

Organization Properties

• id: Unique identifier for the organization
• name: Display name of the organization
• createdBy: ID of the user who created the organization
• createdAt: Timestamp when the organization was created
• updatedAt: Timestamp of the last update to the organization
• version: Version number for optimistic concurrency control
• slug: Optional URL-friendly version of the organization name (frontend only)
• settings: Optional organization-specific configuration (frontend only)

OrganizationSettings Properties

• allowedDomains: List of email domains allowed to join the organization
• requireDomainMatch: Whether users must have an email from an allowed domain
• defaultRole: Default role assigned to new members

Team

The Team model represents a group within an organization.

interface Team {
  id: string
  name: string
  organizationId: string
  createdBy: string // UserId
  createdAt: string // ISO 8601 datetime
  updatedAt: string // ISO 8601 datetime
  version: number
  // Frontend specific fields
  description?: string
  members?: TeamMember[]
  invites?: TeamInvite[]
}

interface TeamMember {
  id: string
  userId: string
  teamId: string
  role: TeamRole
  joinedAt: string
}

interface TeamInvite {
  id: string
  email: string
  teamId: string
  role: TeamRole
  status: 'pending' | 'accepted' | 'rejected'
  createdAt: string
  expiresAt: string
}

type TeamRole = 'admin' | 'member' | 'viewer'

Team Properties

• id: Unique identifier for the team
• name: Display name of the team
• organizationId: ID of the parent organization
• createdBy: ID of the user who created the team
• createdAt: Timestamp when the team was created
• updatedAt: Timestamp of the last update to the team
• version: Version number for optimistic concurrency control
• description: Optional description of the team's purpose (frontend only)
• members: Optional list of current team members (frontend only)
• invites: Optional list of pending team invitations (frontend only)

TeamMember Properties

• id: Unique identifier for the team membership
• userId: ID of the user who is a member
• teamId: ID of the team they belong to
• role: User's role within the team
• joinedAt: Timestamp when the user joined the team

TeamInvite Properties

• id: Unique identifier for the invitation
• email: Email address of the invited user
• teamId: ID of the team they're invited to
• role: Role they'll have if they accept
• status: Current status of the invitation
• createdAt: Timestamp when the invitation was created
• expiresAt: Timestamp when the invitation expires

TeamRole Values

• admin: Can manage team settings and members
• member: Can participate in team activities
• viewer: Can view team content but not modify it

Session

The Session model represents an active user session.

interface Session {
  id: string
  userId: string
  organizationId?: string
  teamId?: string
  expiresAt: string
  createdAt: string
  lastActiveAt: string
}

Session Properties

• id: Unique identifier for the session
• userId: ID of the user who owns the session
• organizationId: Optional ID of the selected organization
• teamId: Optional ID of the selected team
• expiresAt: Timestamp when the session will expire
• createdAt: Timestamp when the session was created
• lastActiveAt: Timestamp of the last activity in the session

Token

The Token model represents the authentication tokens used by the SDK. While the SDK handles token management internally, understanding the token structure can be helpful for debugging and custom implementations.

type TokenType = 'AccessToken' | 'RefreshToken' | 'IdToken'

interface Token {
  id: string
  userId: string
  clientId: string
  tokenType: TokenType
  scopes: string[]
  issuedAt: string // ISO 8601 datetime
  expiresAt?: string // ISO 8601 datetime
  revokedAt?: string // ISO 8601 datetime
}

// JWT payload structure for AccessToken
interface AccessTokenPayload {
  sub: string // User ID
  email: string
  org?: string // Organization ID
  team?: string // Team ID
  roles: string[]
  permissions: string[]
  iat: number // Issued at
  exp: number // Expires at
}

Token Properties

• id: Unique identifier for the token
• userId: ID of the user who owns the token
• clientId: ID of the client application that requested the token
• tokenType: Type of token (AccessToken, RefreshToken, or IdToken)
• scopes: Array of permission scopes granted to the token
• issuedAt: Timestamp when the token was issued
• expiresAt: Optional timestamp when the token expires
• revokedAt: Optional timestamp when the token was revoked

TokenType Values

• AccessToken: Short-lived token used for API authentication
• RefreshToken: Long-lived token used to obtain new access tokens
• IdToken: Token containing user identity information

AccessTokenPayload Properties

The AccessToken payload contains the following claims when decoded:

• sub: Subject (User ID)
• email: User's email address
• org: Optional Organization ID
• team: Optional Team ID
• roles: Array of user roles
• permissions: Array of granted permissions
• iat: Token issuance timestamp
• exp: Token expiration timestamp

Error Types

The error types used throughout the SDK.

interface HeimdallError {
  code: string
  message: string
  details?: Record<string, unknown>
}

// Common error codes
type ErrorCode =
  | 'UNAUTHORIZED'
  | 'FORBIDDEN'
  | 'NOT_FOUND'
  | 'VALIDATION_ERROR'
  | 'RATE_LIMITED'
  | 'INTERNAL_ERROR'

HeimdallError Properties

• code: Machine-readable error code
• message: Human-readable error message
• details: Optional additional error information

ErrorCode Values

• UNAUTHORIZED: User is not authenticated
• FORBIDDEN: User lacks required permissions
• NOT_FOUND: Requested resource doesn't exist
• VALIDATION_ERROR: Invalid input data
• RATE_LIMITED: Too many requests
• INTERNAL_ERROR: Server-side error

Permissions

The permission models define the access control system.

interface Permission {
  id: string
  name: string
  description: string
  category: PermissionCategory
  scope: PermissionScope
}

type PermissionCategory = 'organization' | 'team' | 'user' | 'resource'

type PermissionScope = 'read' | 'write' | 'delete' | 'manage'

interface UserPermission {
  id: string
  userId: string
  permissionId: string
  scope: PermissionScope
  context: PermissionContext
  createdAt: string
  updatedAt: string
}

interface PermissionContext {
  organizationId?: string
  teamId?: string
  resourceId?: string
}

Permission Properties

• id: Unique identifier for the permission
• name: Machine-readable name of the permission (e.g., 'read:team')
• description: Human-readable description of what the permission allows
• category: The type of resource this permission applies to
• scope: The level of access granted

PermissionCategory Values

• organization: Organization-level permissions
• team: Team-level permissions
• user: User-level permissions
• resource: Resource-specific permissions

PermissionScope Values

• read: Ability to view resources
• write: Ability to modify resources
• delete: Ability to remove resources
• manage: Ability to manage permissions and settings

UserPermission Properties

• id: Unique identifier for the permission assignment
• userId: ID of the user who has the permission
• permissionId: ID of the permission being granted
• scope: The level of access granted
• context: The specific context where the permission applies
• createdAt: Timestamp when the permission was granted
• updatedAt: Timestamp of the last update to the permission

PermissionContext Properties

• organizationId: Optional ID of the organization where the permission applies
• teamId: Optional ID of the team where the permission applies
• resourceId: Optional ID of the specific resource where the permission applies