User Models¶

This page documents the data models related to users, tenants, roles, and API keys.

User¶

Represents a user account.

Schema¶

{
  "id": "string (UUID)",
  "email": "string (email)",
  "full_name": "string",
  "tenant_id": "string (UUID)",
  "role": "string (enum)",
  "status": "string (enum)",
  "two_factor_enabled": "boolean",
  "last_login": "string (ISO8601) | null",
  "created_at": "string (ISO8601)",
  "updated_at": "string (ISO8601)"
}

Fields¶

Field	Type	Description
`id`	UUID	Unique user identifier
`email`	string	User email address
`full_name`	string	User's full name
`tenant_id`	UUID	Tenant/organization ID
`role`	Role	User's role
`status`	UserStatus	Account status
`two_factor_enabled`	boolean	Whether 2FA is enabled
`last_login`	ISO8601?	Last login timestamp
`created_at`	ISO8601	Account creation timestamp
`updated_at`	ISO8601	Last modification timestamp

UserStatus Enum¶

Value	Description
`active`	Account is active
`inactive`	Account is disabled
`invited`	Invitation pending acceptance

Example¶

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "full_name": "John Smith",
  "tenant_id": "660e8400-e29b-41d4-a716-446655440001",
  "role": "owner",
  "status": "active",
  "two_factor_enabled": true,
  "last_login": "2026-01-25T09:00:00Z",
  "created_at": "2025-06-15T10:00:00Z",
  "updated_at": "2026-01-25T09:00:00Z"
}

Tenant¶

Represents an organization or tenant.

Schema¶

{
  "id": "string (UUID)",
  "name": "string",
  "slug": "string",
  "subscription_tier": "string (enum)",
  "status": "string (enum)",
  "settings": "TenantSettings",
  "quotas": "TenantQuotas",
  "created_at": "string (ISO8601)",
  "updated_at": "string (ISO8601)"
}

Fields¶

Field	Type	Description
`id`	UUID	Unique tenant identifier
`name`	string	Organization name
`slug`	string	URL-friendly identifier
`subscription_tier`	SubscriptionTier	Subscription level
`status`	TenantStatus	Tenant status
`settings`	TenantSettings	Tenant configuration
`quotas`	TenantQuotas	Usage quotas
`created_at`	ISO8601	Creation timestamp
`updated_at`	ISO8601	Last modification timestamp

SubscriptionTier Enum¶

Value	Description	Limits
`free`	Free tier	5 workbooks, 2 users
`standard`	Standard tier	25 workbooks, 10 users
`premium`	Premium tier	100 workbooks, 25 users
`enterprise`	Enterprise tier	Unlimited

TenantStatus Enum¶

Value	Description
`active`	Tenant is active
`suspended`	Tenant is suspended
`cancelled`	Tenant subscription cancelled

Example¶

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Acme Capital",
  "slug": "acme-capital",
  "subscription_tier": "premium",
  "status": "active",
  "settings": {
    "default_date_format": "YYYY-MM-DD",
    "default_number_format": "#,##0.00",
    "timezone": "America/New_York",
    "two_factor_required": false,
    "session_timeout_minutes": 120,
    "allowed_ip_ranges": []
  },
  "quotas": {
    "workbooks": {"used": 25, "limit": 100},
    "users": {"used": 5, "limit": 25},
    "api_keys": {"used": 3, "limit": 10},
    "storage_gb": {"used": 2.5, "limit": 50}
  },
  "created_at": "2025-06-15T10:00:00Z",
  "updated_at": "2026-01-20T14:30:00Z"
}

TenantSettings¶

Configuration settings for a tenant.

Schema¶

{
  "default_date_format": "string",
  "default_number_format": "string",
  "timezone": "string",
  "two_factor_required": "boolean",
  "session_timeout_minutes": "integer",
  "allowed_ip_ranges": "array[string]"
}

Fields¶

Field	Type	Description
`default_date_format`	string	Date format for exports
`default_number_format`	string	Number format for exports
`timezone`	string	Default timezone (IANA format)
`two_factor_required`	boolean	Require 2FA for all users
`session_timeout_minutes`	integer	Session timeout (15-1440)
`allowed_ip_ranges`	string[]	IP allowlist (CIDR format)

TenantQuotas¶

Usage quotas and limits for a tenant.

Schema¶

{
  "workbooks": "QuotaUsage",
  "users": "QuotaUsage",
  "api_keys": "QuotaUsage",
  "storage_gb": "QuotaUsage"
}

QuotaUsage Schema¶

{
  "used": "number",
  "limit": "number"
}

Fields¶

Field	Type	Description
`workbooks`	QuotaUsage	Workbook quota
`users`	QuotaUsage	User quota
`api_keys`	QuotaUsage	API key quota
`storage_gb`	QuotaUsage	Storage quota in GB

Role¶

User role with permissions.

Schema¶

{
  "name": "string",
  "description": "string",
  "permissions": "array[string]"
}

Fields¶

Field	Type	Description
`name`	string	Role name
`description`	string	Role description
`permissions`	string[]	Granted permissions

Built-in Roles¶

Owner¶

{
  "name": "owner",
  "description": "Tenant owner with full access",
  "permissions": ["*"]
}

Admin¶

{
  "name": "admin",
  "description": "Administrator with most access",
  "permissions": [
    "workbooks:*",
    "calculations:*",
    "compliance:*",
    "scenarios:*",
    "reports:*",
    "alerts:*",
    "mappings:*",
    "users:read",
    "users:invite",
    "users:update",
    "api_keys:*"
  ]
}

Analyst¶

{
  "name": "analyst",
  "description": "Power user for analysis",
  "permissions": [
    "workbooks:read",
    "workbooks:write",
    "calculations:execute",
    "compliance:read",
    "compliance:write",
    "scenarios:read",
    "scenarios:write",
    "reports:read",
    "reports:write",
    "mappings:read"
  ]
}

Viewer¶

{
  "name": "viewer",
  "description": "Read-only access",
  "permissions": [
    "workbooks:read",
    "compliance:read",
    "scenarios:read",
    "reports:read"
  ]
}

APIKey¶

API key for service authentication.

Schema¶

{
  "id": "string (UUID)",
  "name": "string",
  "description": "string | null",
  "key": "string | null",
  "key_prefix": "string",
  "permissions": "array[string]",
  "status": "string (enum)",
  "last_used_at": "string (ISO8601) | null",
  "usage_count": "integer",
  "expires_at": "string (ISO8601) | null",
  "created_by": "string (email)",
  "created_at": "string (ISO8601)"
}

Fields¶

Field	Type	Description
`id`	UUID	API key identifier
`name`	string	Key name
`description`	string?	Key description
`key`	string?	Full key (only on creation)
`key_prefix`	string	Key prefix for identification
`permissions`	string[]	Granted permissions
`status`	APIKeyStatus	Key status
`last_used_at`	ISO8601?	Last usage timestamp
`usage_count`	integer	Number of times used
`expires_at`	ISO8601?	Expiration timestamp
`created_by`	string	Creator's email
`created_at`	ISO8601	Creation timestamp

APIKeyStatus Enum¶

Value	Description
`active`	Key is active and usable
`expired`	Key has expired
`revoked`	Key was revoked

Example¶

{
  "id": "gg0e8400-e29b-41d4-a716-446655440080",
  "name": "Production Integration",
  "description": "API key for automated compliance checks",
  "key_prefix": "cb_live_a1b2c3d4",
  "permissions": [
    "workbooks:read",
    "calculations:execute",
    "compliance:read",
    "compliance:write"
  ],
  "status": "active",
  "last_used_at": "2026-01-25T09:00:00Z",
  "usage_count": 1523,
  "expires_at": "2027-01-25T00:00:00Z",
  "created_by": "owner@acme.com",
  "created_at": "2026-01-25T10:30:00Z"
}

Permission Reference¶

Workbook Permissions¶

Permission	Description
`workbooks:read`	List and view workbooks
`workbooks:write`	Create, update, delete workbooks
`workbooks:*`	All workbook permissions

Calculation Permissions¶

Permission	Description
`calculations:execute`	Evaluate formulas
`calculations:*`	All calculation permissions

Compliance Permissions¶

Permission	Description
`compliance:read`	View compliance results
`compliance:write`	Run compliance tests
`compliance:*`	All compliance permissions

Scenario Permissions¶

Permission	Description
`scenarios:read`	View scenarios
`scenarios:write`	Create and run scenarios
`scenarios:*`	All scenario permissions

Report Permissions¶

Permission	Description
`reports:read`	View reports
`reports:write`	Generate reports
`reports:*`	All report permissions

Alert Permissions¶

Permission	Description
`alerts:read`	View alerts
`alerts:write`	Configure alerts
`alerts:*`	All alert permissions

Mapping Permissions¶

Permission	Description
`mappings:read`	View mappings
`mappings:write`	Create and update mappings
`mappings:*`	All mapping permissions

User Permissions¶

Permission	Description
`users:read`	View users
`users:invite`	Invite new users
`users:update`	Update user roles
`users:remove`	Remove users
`users:*`	All user permissions

API Key Permissions¶

Permission	Description
`api_keys:read`	View API keys
`api_keys:create`	Create API keys
`api_keys:revoke`	Revoke API keys
`api_keys:*`	All API key permissions

Admin Permissions¶

Permission	Description
`tenant:read`	View tenant settings
`tenant:update`	Update tenant settings
`audit:read`	View audit logs
`audit:export`	Export audit logs

UserInvite¶

Request model for inviting a user.

Schema¶

{
  "email": "string (required)",
  "full_name": "string (required)",
  "role": "string (required)",
  "send_email": "boolean | null"
}

Fields¶

Field	Type	Required	Description
`email`	string	Yes	User email address
`full_name`	string	Yes	User's full name
`role`	string	Yes	Role to assign
`send_email`	boolean	No	Send invitation email (default: true)

UserUpdate¶

Request model for updating a user.

Schema¶

{
  "role": "string | null",
  "status": "string | null"
}

Fields¶

Field	Type	Required	Description
`role`	string	No	New role
`status`	string	No	New status (active/inactive)

APIKeyCreate¶

Request model for creating an API key.

Schema¶

{
  "name": "string (required)",
  "description": "string | null",
  "permissions": "array[string] (required)",
  "expires_at": "string (ISO8601) | null"
}

Fields¶

Field	Type	Required	Description
`name`	string	Yes	Key name (1-100 chars)
`description`	string	No	Key description
`permissions`	string[]	Yes	Permissions to grant
`expires_at`	ISO8601	No	Expiration date

TokenResponse¶

Response from authentication endpoints.

Schema¶

{
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "string"
}

Fields¶

Field	Type	Description
`access_token`	string	JWT access token (15 min validity)
`refresh_token`	string	JWT refresh token (7 day validity)
`token_type`	string	Token type (always "bearer")

Example¶

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Token Claims¶

Access Token¶

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "660e8400-e29b-41d4-a716-446655440001",
  "role": "owner",
  "type": "access",
  "jti": "unique-token-id",
  "iat": 1706200000,
  "exp": 1706200900
}

Refresh Token¶

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "660e8400-e29b-41d4-a716-446655440001",
  "type": "refresh",
  "jti": "unique-token-id",
  "iat": 1706200000,
  "exp": 1706804800
}