Access Service

Permission and authorization management.

On This Page

• What It Does
• Key Capabilities
• How It Fits Together
• Common Use Cases
• What You Don’t Have to Build
• Technical Details

What It Does

The Access Service manages authorization and secure resource access across the platform. It handles permission checking for user actions, role-based access control, token generation for secure share links, and API key management for service-to-service auth. Every service uses the Access Service to answer the question: “Can this request access this resource?”

Key Capabilities

Permission Naming Convention

Permissions follow a consistent pattern for organization:

(scope/service)/(action)-(target)

Examples:

• customer/view-client
• user/manage-all-customer-users
• product/edit-billing-details

How It Fits Together

┌──────────────────────────────────────┐
│           Access Service             │
│  ┌───────────┬─────────┬───────────┐ │
│  │Permissions│ Tokens  │ API Keys  │ │
│  └───────────┴─────────┴───────────┘ │
└──────────────────┬───────────────────┘
                   │
                   ▼
┌──────────────────────────────────────┐
│           All Services               │
│  • Check user permissions            │
│  • Validate share links via tokens   │
│  • Authenticate API requests         │
└──────────────────────────────────────┘

Every service uses the Access Service to check permissions, validate tokens, or authenticate API keys before allowing access to protected resources.

Common Use Cases

• Role-based access: Admins can manage users, viewers can only read with automatic permission checking
• Customer-scoped roles: Permissions that apply within a specific customer context with automatic isolation
• Feature gating: Control access to premium features via permissions with real-time updates
• Role assignment control: Automatic prevention of privilege escalation
• Secure share links: Generate tokens to share documents, reports, or resources via URL — with expiration and use limits
• Temporary access grants: Single-use or time-limited tokens for one-time actions like password reset or email verification
• API key management: Multi-tenant API keys with automatic TTL expiration and scope validation
• Use limits: Per-user, per-resource rate limiting with transactional counting

What You Don’t Have to Build

• Multi-level permission checking logic (single, any, all)
• Real-time permission cache management
• Role encompassing and privilege escalation prevention
• Secure token generation for share links and temporary access
• Token lifecycle management (expiration, use limits, enrichment)
• Multi-tenant API key isolation with cascading invalidation
• Transactional use limit counters
• Decorator-based authorization guards
• Cryptographic hashing and secure key generation
• Event-driven access control workflows
• Scheduled token cleanup jobs
• Secure error handling with information leak prevention

Technical Details

Heavy-Lifting Features

1. Multi-Level Permission Checking

Automatic permission evaluation with multiple strategies:

 PermissionService provides:
  - hasPermission()      - Single permission check
  - hasAnyPermission()   - OR logic (user needs ANY of these)
  - hasAllPermissions()  - AND logic (user needs ALL of these)
  - getPermissions()     - Lazy-loaded permission retrieval
  - getEncompassedRoles() - Which roles can this user assign to others

Automatic resolution:

• Product → Role → Permissions mapping
• Multi-product permission merging (user has access to multiple products)
• Role encompassing calculations (prevents privilege escalation)

What customers avoid:

• Writing permission check logic
• Implementing AND/OR permission combinations
• Managing product-to-role-to-permission hierarchies
• Calculating role qualification logic

2. Real-Time Permission Updates

Automatic permission cache management with live updates:

• Reactive Listeners: Permission maps automatically update via database listeners
• Zero Restart Required: Permission changes propagate without app deployment
• Static Service Design: Zero-instantiation overhead for permission checks
• Change Detection: Automatic invalidation when permission configurations update

What customers avoid:

• Building cache invalidation systems
• Implementing pub/sub for permission updates
• Writing listener management code
• Handling cache consistency

3. Token Services for Secure Resource Sharing

Generate unique, secure tokens to protect any resource. This is the go-to solution when you need to create shareable links — for example, sharing a document, granting temporary access to a report, or enabling one-time downloads.

AccessTokenService provides:
  - createToken()              - Generate token with custom data attached
  - getValidatedToken()        - Retrieve and validate in one call
  - getAndUseValidatedToken()  - Validate, increment use count, return token
 
Token features:
  - Custom expiration dates (TTL)
  - Use limits (allowedUses/useCount)
  - Enable/disable tokens (soft delete)
  - Attach any custom data to the token

Token enrichment for dynamic links:

Tokens can be enriched before saving — for example, to auto-generate a dynamic link that embeds the token. This is useful when you need a mobile-friendly share URL that routes users correctly.

await accessTokenService.createTokenWithEnricher(
  { ownerId, type: 'document-share', expiredDate },
  { documentId, permissions: ['view'] },
  new DynamicLinkTokenEnricher(token => `https://app.example.com/share/${token}`)
)

What customers avoid:

• Building secure token generation
• Implementing expiration and use limit logic
• Writing share link infrastructure
• Managing token lifecycle states

4. Multi-Tenant API Key Management

Create scoped API keys with automatic tenant isolation:

ApiKeyManager handles:
  - customerKey field: Customer-level isolation
  - partitionId field: Logical partitioning within customers
  - foreignKey field: External reference tracking
  - scopes: Fine-grained access control
  - ttl: Automatic expiration
 
Bulk operations:
  - expireAllForCustomer()    - Invalidate all customer keys
  - expireAllForPartition()   - Partition-scoped invalidation
  - expireAllForForeignKey()  - Cascading invalidation

Security features:

• Obfuscated failure reasons (prevents information leakage)
• All errors return identical messages regardless of root cause
• Prevents tenant enumeration attacks

What customers avoid:

• Building multi-tenant isolation logic
• Implementing cascading invalidation
• Writing secure error handling
• Managing API key lifecycles

5. Use Limit Enforcement

Transactional use counting with automatic enforcement:

UseLimitService:
  - Fine-grained limits: per userId + type + itemId
  - Transactional increment (prevents race conditions)
  - Automatic limit checking before operations
  - USE_LIMIT_EXCEEDED error thrown when exceeded

What customers avoid:

• Writing distributed counters
• Implementing transactional updates
• Building rate limiting logic
• Handling concurrent access

6. Decorator-Based Access Control

Automatic endpoint-level authorization enforcement:

@ApiKeyRequireScope('read', 'write')  // Require API key with scopes
async getResource() { ... }
 
@TokenWithScope('document-view')      // Require authorization token
async viewDocument() { ... }
 
Guards automatically:
  - Parse and validate API keys or tokens
  - Check scopes against required scopes
  - Validate TTL expiration
  - Delete single-use tokens after validation

What customers avoid:

• Writing authorization middleware
• Implementing scope validation logic
• Managing token parsing and validation
• Building automatic cleanup mechanisms

7. Cryptographic Security

Built-in cryptographic operations:

API Key Hashing:
  - Configurable salt rounds (default: 10)
  - One-time plaintext delivery, then encrypted storage
  - Constant-time comparison (encryption.compare())
 
Token Security:
  - 32-byte random key generation
  - Hashed storage for authorization tokens
  - ID:Token format (separates identity from secret)

What customers avoid:

• Implementing secure hashing
• Managing salt rounds
• Writing constant-time comparison
• Building key generation logic

8. Event-Driven Architecture

Automatic event publishing for all access operations:

API_KEY_CREATED  → Publish event → Check TTL → Schedule expiration
API_KEY_UPDATED  → Publish event
API_KEY_DELETED  → Publish event
TOKEN_EXPIRED    → Publish event

What customers avoid:

• Building event publishing infrastructure
• Implementing task scheduling
• Managing event-driven workflows
• Writing audit logging

🤖 This documentation was generated using AI and human-proofed for accuracy.