Aptli

System Settings

System settings control application-wide behaviour — who can register, how long sessions last, how long deleted records are retained, and what permissions new users start with. Settings are managed at Admin → App Settings and require the appSettingSchemasModify admin right.

Security Architecture

Aptli uses a four-layer security model, enforced server-side:

Layer 1: Authentication

Who you are - verifies user identity before access.

  • Password-based login (with complexity requirements)
  • OAuth providers (Google, GitHub, Microsoft, Keycloak)
  • Two-factor authentication (SMS)
  • Email validation required
  • Session management with expiry
  • Hard lock after failed attempts

Layer 2: Admin Rights (Permissive)

What you CAN modify - explicit permission grants.

  • Create/update/delete permissions per model
  • Super rights: appSettingSchemasModify, adminRightsModify, viewDeleted
  • Scoped to actions (can create but not delete)
  • Default: View-only access

Layer 3: Role Restrictions (Restrictive)

What you CANNOT see - field-level data filters.

  • Model + field + comparison + value filters
  • Applied server-side before database query
  • Cannot bypass via API calls, exports, or screenshots
  • Multiple restrictions combine (AND logic)

Layer 4: Server-Side Enforcement

Restrictions are enforced on the server — unauthorized data is never sent to your browser.

Why this matters:

  • Client-side filtering: Data sent to browser, hidden with JavaScript (bypassable via dev tools)
  • Server-side filtering: Data never sent to unauthorized users (secure)

Aptli enforces all filters on the server — unauthorized data never reaches the client.

Application Settings

Access Required: appSettingSchemasModify admin right

Navigate to: Admin → App Settings

Authentication Settings

Allow Registration:

  • true - Users can self-register if domain matches
  • false - Admin must manually create accounts
  • Default: false (controlled access)

Maintenance Mode:

  • When on, non-admins are blocked from writes and see a maintenance banner
  • Default: off

Allowed Domains is not a setting here. The email allowed-domains list is environment-only (NUXT_ALLOWED_DOMAINS) and is managed from the support portal's My Environment page.

Active Login Methods are not checkboxes here. Which methods appear is derived from which OAuth client IDs are present in the environment (NUXT_OAUTH_GOOGLE_CLIENTID, NUXT_OAUTH_GITHUB_CLIENTID, NUXT_OAUTH_MICROSOFT_CLIENTID, NUXT_OAUTH_KEYCLOAK_CLIENTID). Username/password is always available. There is no per-method toggle.

Require Two-Factor Authentication:

  • A single on/off setting (requireTwoFactorAuth)
  • true - SMS 2FA required for every login; there is no grace period
  • false - 2FA optional
  • Default: false

Session Security

Max Login Attempts:

  • Number of failed logins before hard lock
  • Valid range: 1-20 attempts
  • Default: 5

Lockout Time:

  • How long, in seconds, a failed attempt counts toward the lock; older failures drop off and the lock self-clears
  • Valid range: 300-3600 seconds
  • Default: 900 (15 minutes)

Session, CSRF token, and session-expiry timeouts have moved to the provisioning portal. They are shown read-only in the Environment section at the bottom of the settings page and are no longer edited here.

Data Retention

Log Retention Days:

  • The only retention control on this page (logRetentionDays)
  • How many days of application logs are kept
  • Valid range: 1-365 days
  • Default: 30

There is no "Soft Delete Retention" or "Version Compression Schedule" dropdown. Per-schema soft-delete archival retention is configured in code (via each schema's stampPlugin settings), not from this page.

Transaction History:

  • Inventory transactions are an immutable audit trail
  • Retention is environment-configured (NUXT_TRANSACTION_RETENTION_MONTHS), shown read-only in the Environment section

Other Controls On This Page

Beyond authentication and retention, the settings page also exposes:

  • Map display zoom — for each geometry type (point, line, polygon), a "show above zoom" and "show below zoom" value (6 fields total) that govern when features appear on the map.
  • Branding — app name, print-footer text, light/dark logos, app icon, and default timezone.
  • Fulfillment catalog enforcement — two independent soft-nudge toggles, enforceRegisteredResources and enforceRegisteredActivities, that warn when a materials line or work-order activity is ad-hoc rather than from the catalog. They never block saving.
  • Security alert recipients — users notified when an account is hard-locked.
  • Billing contact emails — finance/AP addresses that receive license-expiry and seat-limit alerts (no app account needed).
  • QR code TTLs — default time-to-live (minutes) for pickup and transfer codes, plus the QR lookup results-per-collection limit.
  • Maintenance mode — see Authentication Settings above.

AI provider and model are not set here. They are configured in the AI chat slideover's settings, controlled at the org level by the chat layer's enabled setting and at the deployment level by which provider API keys are present in the environment.

New User Defaults

Default Roles:

  • Roles auto-assigned to new accounts
  • Empty = no automatic restrictions
  • Default: none (admin assigns manually)

Admin Rights for New Users:

  • New users start with no admin rights (view-only); grant rights per user from their profile
  • Admin rights are an à-la-carte per-user array; they are never granted through a role

Example Configurations:

Field Worker:

  • Default roles: ["Field Workers"]
  • Admin rights granted on the user: reportsCreate

Office Coordinator:

  • Default roles: none
  • Admin rights granted on the user: workOrdersCreate, stockItemsCreate, stockItemsUpdate

API Keys

API keys let an external system call Aptli without a human logging in — for ArcGIS/Postgres sync, data-warehouse export, or your own tooling. Managed at Admin → App Settings → API Keys. Requires appSettingSchemasModify.

Limits

  • Maximum 3 keys per deployment. Revoke an existing key before creating a new one.
  • Each key has its own isolated rate-limit bucket (same thresholds as an interactive user: ~2,700 requests/minute for reads, ~900/minute for writes). One busy integration cannot starve another key or the human user pool.

Read-only keys

When creating a key you can toggle Read-only. A read-only key is blocked from all write requests (POST / PUT / PATCH / DELETE) at the session layer — even if write rights were granted. Use this for integrations that only need to pull data.

Creating a key

  1. Admin → App Settings → API Keys → Generate key
  2. Give the key a name (e.g. ArcGIS sync).
  3. Choose which admin rights to grant. Empty = no write rights (recommended unless the integration needs to write).
  4. Toggle Read-only if the integration only reads.
  5. Copy the key — it is shown once only and cannot be recovered.

Using a key

Pass the key as a Bearer token on every request:

Authorization: Bearer aptli_<your-key>

The key authenticates as a low-privilege service user. All endpoint authorization still applies — a key can only do what its granted rights allow.

Revoking a key

Click Revoke next to the key in the table. Revocation is immediate: the next request using that key returns 401. The service user account is also deactivated.

Security notes

  • Keys are stored as SHA-256 hashes — a database leak cannot expose the raw key.
  • Keys bypass CSRF protection (no browser cookie, no CSRF attack surface) but are still bound by all endpoint authorization checks.
  • API keys cannot themselves create other API keys.

Communications Health

The settings page includes a collapsed Communications health section (between the Environment list and the Danger Zone). Open it to see the live state of the messaging pipelines:

  • Email / SMS / Push delivery — whether the provider credentials are configured, and how many messages are pending or retrying in each queue. A missing provider key does not produce errors: messages quietly queue forever, and this panel is where that becomes visible.
  • SMS quota — when a monthly SMS cap is set for the deployment, the SMS row shows used/cap for the current month and turns amber when the cap is reached.
  • Queue backend — whether the job store (Valkey) is connected; an in-memory fallback warning means queued messages will be lost on restart.
  • Security alert recipients — how many addresses will receive account-lock and quota alerts. Zero means those alerts go nowhere; configure recipients on this same page.
  • Email domain coverage — when a domain allowlist is active, the number of active users whose email domain has fallen off the list (they cannot receive any email until the list is updated or they are archived).

Rows show a green check when healthy and an amber warning otherwise. Use Refresh to re-poll after changing environment configuration.

Self-Hosted Deployment

For self-hosted deployment instructions, see the System Administrator Guide.

Security Best Practices

SSL/TLS Required:

  • Use HTTPS in production (not HTTP)
  • Free certificates: Let's Encrypt
  • Refuse HTTP connections (redirect to HTTPS)

Firewall Configuration:

  • Allow: HTTPS (443), SSH (22)
  • Deny: database ports from the public internet
  • Restrict: Admin pages to VPN or IP allowlist

Session Security:

  • Session signing keys should be long, random, and rotated quarterly
  • Use short session expiry in high-security environments
  • See the Deployment Guide for server-side session configuration

Database Security:

  • Database authentication enabled
  • Separate user credentials (not root)
  • Encrypted database connections
  • Regular backups (automated, tested restoration)

OAuth Secrets:

  • Store in environment variables (not in code)
  • Rotate quarterly
  • Revoke unused OAuth apps

File Upload Security:

  • File scanning enabled in production
  • File size limits enforced
  • Allowed file types restricted
  • Storage quarantine for suspicious files

Monitoring:

  • Failed login attempts (detect brute force)
  • Authorization failures (detect unauthorized access attempts)
  • Unusual API usage patterns
  • Database connection failures

Compliance Considerations

Data Residency: Self-hosted mode allows control of data location:

  • Host in specific geographic region
  • Meet regulatory requirements (GDPR, HIPAA, etc.)
  • Control data access physically

Audit Trail: Aptli maintains audit trails for:

  • Authentication attempts (success/failure)
  • Admin right usage (who modified what)
  • Role restriction changes
  • Transaction history (inventory movements)
  • Version history (feature changes)
  • Soft deletes (who deleted what, when)

Data Export: All data exportable for compliance:

  • CSV export for non-geo data
  • GeoJSON export for features (via the Data Transfer button on the map toolbar)
  • Transaction reports (inventory audit)
  • User access logs

Data Retention: Retention policies:

  • Application log retention (logRetentionDays, set on the settings page)
  • Soft-delete archival (per-schema, configured in code)
  • Transaction history (immutable audit trail; environment-configured retention)
  • Audit history (capped query window — see the Audit History admin guide)