Roles & Permissions

Borderbolt uses a role-based access control (RBAC) system to manage user permissions. This page explains the pre-defined roles, permission groups, and how to create custom roles.

Overview

Roles group related permissions together for easy assignment to users. Instead of assigning permissions individually, you assign a role that includes all necessary permissions.

Permissions control access to specific features, data, and actions within Borderbolt. The system includes 15 permission groups with 69 individual permissions.

Key Concepts:

• Users can have multiple roles
• Permissions are additive (user gets union of all role permissions)
• Organization-scoped roles only apply within specific organization
• Route middleware enforces permissions at the backend level
• Frontend navigation automatically hides unauthorized features

Pre-Defined Roles

Borderbolt includes 9 pre-configured system roles for common use cases. These roles can be assigned as-is or customized to match your organization’s needs.

Role Summary

Admin

Full administrative access to organization settings, users, and data.

Permissions:

• All declaration permissions (view, create, edit, delete, submit)
• All transit permissions
• All customer and item master permissions
• Settings management
• User management
• Role and permission management
• Invoice and billing management
• AI import management
• Reports and analytics
• System configuration

Typical Users: Company owners, system administrators, office managers

Use Cases:

• Overall system management
• User and role administration
• Configuration and settings
• Financial oversight

Manager

Operational management role with access to declarations, customers, and reports, but not system settings.

Permissions:

• View, create, edit declarations
• Submit declarations to customs
• Manage customers and item master
• View and create invoices
• Access reports and analytics
• Manage dossiers and guarantees
• Transit declarations
• AI import review

Excluded:

• System settings (email, security, billing)
• User management
• Role configuration

Typical Users: Operations managers, team leads, senior staff

Use Cases:

• Day-to-day operations oversight
• Customer relationship management
• Declaration review and approval
• Team coordination

Customs Manager

Specialized role for senior customs professionals managing declaration quality and compliance.

Permissions:

• All declaration permissions
• Transit declarations (NCTS5)
• Compliance and measure checking
• Tariff and HS code management
• Customer master data
• AI import review and approval
• Reports and analytics
• Document management

Excluded:

• System settings
• User management
• Invoicing and billing
• Portal configuration

Typical Users: Senior declarants, customs compliance officers, tariff specialists

Use Cases:

• Declaration quality control
• Customs compliance oversight
• Tariff classification review
• Training junior declarants

Senior Declarant

Experienced declarant with full declaration permissions and customer management.

Permissions:

• View, create, edit, delete declarations
• Submit declarations to customs
• Manage declaration documents
• Create and edit customers
• Item master management
• File import
• Draft declarations
• View own invoices and reports

Excluded:

• System settings
• User management
• AI import configuration
• Billing settings
• Other users’ declarations (unless assigned)

Typical Users: Experienced customs declarants, logistics coordinators

Use Cases:

• Independent declaration processing
• Customer onboarding
• Complex declaration types
• Mentoring junior staff

Junior Declarant

Entry-level declarant with limited permissions requiring oversight.

Permissions:

• View declarations
• Create and edit draft declarations
• Add declaration lines
• Upload documents
• View customers and item master
• File import with templates

Excluded:

• Submit declarations (requires review)
• Delete declarations
• Edit submitted declarations
• Create/edit customers
• Settings access
• Invoicing

Typical Users: New declarants, interns, trainee staff

Use Cases:

• Declaration data entry
• Learning customs processes
• Supervised declaration creation
• Low-risk declarations

Workflow: Junior Declarant creates draft → Senior Declarant or Manager reviews and submits

Data Entry

Focused role for administrative staff handling data entry tasks.

Permissions:

• View declarations
• Create and edit draft declarations
• File import
• View customers and item master
• Document upload
• View own tasks

Excluded:

• Submit declarations
• Edit submitted declarations
• Create/edit customers
• Settings access
• Reports access
• Invoicing

Typical Users: Administrative assistants, data entry clerks, back-office staff

Use Cases:

• Bulk data entry from customer files
• Document scanning and upload
• Draft declaration creation for review
• Template-based imports

Viewer

Read-only access for oversight and auditing purposes.

Permissions:

• View declarations
• View customers and item master
• View documents
• View reports (if granted specifically)
• View invoices (own customer only)

Excluded:

• Create or edit any data
• Submit declarations
• Delete data
• Settings access
• User management

Typical Users: Accountants, auditors, read-only stakeholders, customer service

Use Cases:

• Financial auditing
• Customer service inquiries
• Read-only oversight
• Reporting and analytics

Support

System support role with full access for troubleshooting and customer support purposes.

Permissions:

• All permissions (equivalent to Admin role)
• Full declaration, customer, and system access
• Settings management
• User management

Excluded:

• None - has all permissions

Typical Users: Borderbolt support staff, technical support team, help desk personnel

Use Cases:

• Customer support and troubleshooting
• System diagnostics and debugging
• User assistance and training
• Emergency access for critical issues

Security Note: Support role should only be assigned to authorized Borderbolt support personnel or internal support staff who require full access for troubleshooting purposes.

Permission Groups

Permissions are organized into 15 functional groups for easier management. Each group contains related permissions that control access to specific features.

Permission Groups Overview

Declarations

Control access to import/export declaration features.

Permissions (8 total):

• declarations.view - View declaration list and details
• declarations.create - Create new declarations
• declarations.edit - Edit declaration header and lines
• declarations.delete - Delete declarations (soft delete)
• declarations.submit - Submit to customs
• declarations.download - Download declaration documents
• declarations.noodprocedure - Generate noodprocedure (emergency declaration)
• declarations.view_change_history - View change history and audit trail

Transit

Control access to NCTS5 transit declarations.

Permissions (5 total):

• transit.view - View transit declarations
• transit.create - Create transit declarations (T1, T2)
• transit.edit - Edit transit declarations
• transit.delete - Delete transit declarations
• transit.submit - Submit to NCTS5 system

Drafts

Control access to draft declarations (not yet submitted).

Permissions (4 total):

• drafts.view - View draft declarations
• drafts.create - Create new drafts
• drafts.edit - Edit draft declarations
• drafts.delete - Delete drafts

Customers

Control access to customer master data.

Permissions (4 total):

• customers.view - View customer list and details
• customers.create - Create new customers
• customers.edit - Edit customer information
• customers.delete - Delete customers (soft delete)

Item Master

Control access to product/item master data.

Permissions (7 total):

• item_master.view - View item master list
• item_master.create - Create new items
• item_master.edit - Edit item information
• item_master.delete - Delete items
• item_master.classify - Classify items (HS/TARIC codes)
• item_master.approve - Approve/reject pending changes
• item_master.verify - Verify item classifications

Documents

Control access to document management.

Permissions (6 total):

• documents.view - View uploaded documents
• documents.upload - Upload new documents
• documents.download - Download documents
• documents.generate_sad - Generate SAD (Single Administrative Document)
• documents.generate_cmr - Generate CMR (International Consignment Note)
• documents.generate_atr - Generate A.TR (Turkey Movement Certificate)

File Import

Control access to bulk file import features.

Permissions (2 total):

• file_import.use - Use file import functionality
• file_import.manage_templates - Manage import templates

Settings

Control access to system configuration.

Permissions (5 total):

• settings.view - View settings pages
• settings.edit - Edit general settings
• settings.company - Manage company settings
• settings.portal - Manage portal settings
• settings.declarants - Manage declarants

Users

Control access to user management.

Permissions (5 total):

• users.view - View user list
• users.create - Create new users
• users.edit - Edit user information
• users.delete - Delete users (soft delete)
• users.manage_roles - Manage roles and permissions

Reports

Control access to reports and analytics.

Permissions (2 total):

• reports.view - View reports
• reports.export - Export reports to Excel/PDF

AI Import

Control access to AI-powered email import features.

Permissions (2 total):

• ai_import.use - Use AI import features
• ai_import.view_all - View all AI imports (workbench)

Compliance

Control access to compliance and tariff features.

Permissions (2 total):

• compliance.view - View compliance dashboard
• compliance.manage - Manage compliance actions

Notifications

Control notification-related permissions.

Permissions (2 total):

• notifications.view - View notification logs
• notifications.send - Send customer notifications

Dossiers

Control access to dossier management (guarantee tracking).

Permissions (4 total):

• dossiers.view - View dossier list
• dossiers.create - Create new dossiers
• dossiers.edit - Edit dossier information
• dossiers.delete - Delete dossiers

Invoicing

Control access to billing and invoicing features.

Permissions (11 total):

• invoicing.view - View invoices
• invoicing.create - Create invoices
• invoicing.edit - Edit invoices
• invoicing.delete - Delete invoices
• invoicing.finalize - Finalize invoices
• invoicing.payments - Mark invoices as paid and manage prepayments
• invoicing.rate_cards - Manage rate cards
• invoicing.billable_items - Manage billable items
• invoicing.statements - View and manage statements
• invoicing.accounting - Manage accounting integrations
• invoicing.settings - Manage invoice & statement settings (Admin)
• invoicing.designer - Manage invoice & statement templates (Admin)

Custom Role Creation

Creating a Custom Role

Create roles tailored to your organization’s specific needs.

Process:

1. Navigate to Settings → Roles & Permissions
2. Click “Create New Role”
3. Enter role name (e.g., “Customs Auditor”, “Billing Specialist”)
4. Optionally add description
5. Select permissions from permission groups
6. Save role
7. Assign to users as needed

Example Custom Roles:

Billing Specialist

• view_declarations
• view_customers
• view_invoices
• create_invoices
• edit_invoices
• send_invoices
• export_invoices
• view_reports

Use Case: Dedicated billing team member who handles invoicing but doesn’t need declaration editing.

Compliance Officer

• view_declarations
• view_customers
• view_measures
• check_compliance
• view_tariff_data
• view_reports
• view_audit_logs

Use Case: Compliance team member who audits declarations but doesn’t create them.

Customer Service

• view_declarations
• view_customers
• view_documents
• download_documents
• view_invoices

Use Case: Customer service representative who needs read-only access to answer customer inquiries.

Editing Existing Roles

Modify permissions for pre-defined or custom roles.

Process:

1. Navigate to Settings → Roles & Permissions
2. Click role name to edit
3. Add or remove permissions
4. Save changes
5. Changes apply immediately to all users with that role

Deleting Custom Roles

Remove roles that are no longer needed.

Requirements:

• No users currently assigned to the role
• Cannot delete pre-defined roles (Admin, Manager, etc.)

Process:

1. Reassign all users to different roles
2. Navigate to Settings → Roles & Permissions
3. Click delete icon next to role
4. Confirm deletion

Best Practices

Principle of Least Privilege

Grant users the minimum permissions required to perform their job functions.

Benefits:

• Reduces risk of accidental data changes
• Limits damage from compromised accounts
• Ensures accountability
• Simplifies compliance auditing

Example:

• Customer service → Viewer role (read-only)
• Junior staff → Data Entry or Junior Declarant (limited edit)
• Senior staff → Senior Declarant or Manager (full operational access)
• IT admin → Admin (system management)

Role Assignment Strategy

Single Role per Function:

• Prefer assigning one primary role per user
• Add secondary roles only when necessary
• Avoid overlapping permissions

Example Structure:

├── Admin (2-3 users) - Full access
├── Manager (3-5 users) - Operations
├── Senior Declarant (5-10 users) - Declaration processing
├── Junior Declarant (10-20 users) - Assisted processing
├── Data Entry (2-5 users) - Data entry only
└── Viewer (3-5 users) - Read-only

Regular Permission Audits

Review user roles and permissions periodically.

Quarterly Review:

• Check for users with excessive permissions
• Remove access for users who changed roles
• Verify new users have appropriate permissions
• Update roles to match organizational changes

Audit Questions:

• Do all Admins still require admin access?
• Are there users with multiple redundant roles?
• Have any users left or changed departments?
• Are custom roles still relevant?

Separation of Duties

Separate critical functions across different roles.

Example Separations:

• Declaration Creation (Junior Declarant) ≠ Declaration Submission (Senior Declarant)
• Invoice Creation (Manager) ≠ Invoice Approval (Admin)
• Customer Creation (Data Entry) ≠ Customer Approval (Manager)

Benefits:

• Prevents fraud and errors
• Ensures peer review
• Improves data quality
• Compliance with SOX, ISO 27001

How Permissions Work

Access Control

All pages and actions are protected by permissions. When a user tries to access a page or perform an action they don’t have permission for, they will see an “Access Denied” message.

Navigation

Menu items and buttons are automatically hidden if the user lacks the required permission. This ensures users only see features they have access to.

Syncing Permissions

When new permissions are added (e.g., after a system update), an administrator must sync the permissions database. This can be done from the Settings > System page or by contacting support.

What syncing does:

1. Adds any new permissions to the system
2. Updates all system roles with their correct default permissions
3. Refreshes the permission cache

Updating Roles & Permissions

1. Navigate to Settings → Roles & Permissions
2. View list of all roles and their assigned permissions
3. Click role name to edit
4. Add/remove permissions using checkboxes (organized by group)
5. Save changes
6. Changes apply immediately to all users with that role

Permissions

To edit roles and permissions, users must have the User Management permission. This is typically assigned to:

• Admin role

Related Configuration

• User Management - Assign roles to users
• Security Settings - Configure authentication and access control
• Customer Portal - Portal-specific roles and permissions

Troubleshooting

User Cannot Access Feature

Problem: User reports they cannot access a feature despite having a role that should grant access.

Solutions:

• Verify user is assigned the correct role: User Management → View User
• Check role has the required permission: Settings → Roles & Permissions → View Role
• Ensure user has logged out and back in (permissions cached on login)
• Contact your administrator to clear the application cache if issues persist
• Check for permission conflicts (multiple roles with contradictory permissions)

Too Many Permissions

Problem: User has access to features they shouldn’t.

Solutions:

• Review all roles assigned to user (permissions are additive)
• Remove unnecessary roles from user
• Create more granular custom role if needed

Custom Role Not Appearing

Problem: Created custom role but it doesn’t appear in user assignment dropdown.

Solutions:

• Verify role was saved successfully
• Clear browser cache and reload
• Check role is active (not disabled)
• Ensure you’re in the correct organization (if managing multiple organizations)
• Review application logs for errors

Permission Changes Not Taking Effect

Problem: Updated role permissions but users still have old access.

Solutions:

• Users must log out and back in for permission changes to take effect
• Contact your administrator to restart background processing services if needed
• Contact your administrator to clear the application cache
• Wait a few minutes for session cache to expire
• Verify changes were saved correctly in Settings → Roles & Permissions