SofiaLocks Integration

​

Overview

SofiaLocks is a mobile-first smart lock system powered by Jago Cloud. The Nexudus integration automatically provisions customers in your SofiaLocks account and manages their access permissions based on their active plans, passes, bookings, and contract desk assignments. Key features:

• Mobile app access — customers unlock doors from the Nexudus Passport Whitelabel app
• Credential-based access control — fine-grained permission management via lock tags
• Time-bound visitor access — temporary access codes for guests
• Automatic check-ins — door open events trigger check-ins in Nexudus

​

Capabilities

​

How It Works

​

Access Control Model

SofiaLocks uses credential rules to grant access:

1. Each customer is provisioned as a user in SofiaLocks
2. Each door has associated lock tags that control access
3. When you map inventory (passes, resources, desks) to lock tags, Nexudus creates credential rules linking the customer to those lock tags
4. When the customer opens the Nexudus Passport app, they see only the doors they have access to

Note: Desk access is granted through active contracts—customers receive access to desks included in their own contracts or, for team billing, desks in the paying member’s contracts.

​

Multi-Door Support

A single inventory item (like a pass, resource, or desk) can grant access to multiple doors. For example, a “Full Access” pass might provide access to the main entrance, office floors, and meeting rooms.

​

Prerequisites

Before connecting Nexudus to SofiaLocks, you’ll need:

• An active SofiaLocks account with administrative access
• Your Location ID (visible in your SofiaLocks dashboard URL: api-{location_id}.jago.cloud)
• Your SofiaLocks username and password
• At least one smart lock installed and configured in SofiaLocks

​

Configuration

​

Step 1: Connect to SofiaLocks

1. Go to Settings > Integrations in the Nexudus dashboard
2. Find SofiaLocks and click Configure
3. Enter your credentials:
   • Location ID — the identifier from your SofiaLocks URL
   • Username — your SofiaLocks admin username
   • Password — your SofiaLocks admin password
4. Click Connect

Nexudus will authenticate with SofiaLocks and retrieve your doors and lock tags.

​

Step 2: Configure Presence Tracking

Presence tracking controls which door events trigger check-ins in Nexudus. For each door, select an action: Best practice: Only configure check-in tracking for your main entrance. Tracking every door creates excessive check-in records.

​

Step 3: Map Passes to Lock Tags

Passes are the primary mechanism for granting access in Nexudus:

1. In the Passes section, locate the pass you want to configure
2. Select the lock tags for doors this pass should unlock
3. Access is automatically limited to the pass’s validity window

Important: Plans (membership tiers) grant access indirectly through the passes they include. When a customer signs a contract on a plan, they automatically receive the passes associated with that plan, which then determines their door access. Example mapping:

• Day Pass → Main entrance only
• 24/7 Access Pass → Main entrance + Office floors
• Premium Access Pass → Main entrance + Office floors + Meeting rooms

​

Step 4: Map Resources to Lock Tags

Resources (meeting rooms, equipment) grant temporary access during bookings:

1. In the Resources section, locate the resource
2. Select the lock tags for doors related to this resource
3. Customers will receive access during their booking window (starting 15 minutes before)

​

Step 5: Map Desks to Lock Tags

Floor plan desks can grant access to specific zones or floors:

1. In the Desks / Offices section, find the desk
2. Select the lock tags for the zone or floor where the desk is located
3. Customers with contracts that include these desks will receive ongoing access

Team billing: If a customer is part of a team using merged billing (where one member pays for others), they also receive access to any desks assigned to the paying member’s contracts.

​

Visitor Access

When you create a visitor in Nexudus:

1. The visitor is automatically provisioned in SofiaLocks
2. They receive time-limited access based on the visit window
3. Access expires automatically after the visit ends
4. The system removes their access and user profile shortly after expiry

Visitors don’t need a full customer account — they receive temporary credentials valid only during their scheduled visit.

​

How Visitor Access is Determined

SofiaLocks determines which doors a visitor can access using this priority:

1. Booking-based visitors (guests invited to a booking):
   • If the booking is for a resource (meeting room), the visitor gets access to that resource’s lock tags
   • If the booking includes a desk assignment, the visitor gets access to that desk’s lock tags
   • This gives visitors access only to the specific areas they need during their booking
2. General visitors (not linked to a booking):
   • They receive access to the default visitor lock tags configured in your SofiaLocks settings
   • Use this for reception areas or common visitor zones

​

Access Time Windows

Visitor access includes a 15-minute buffer:

• Access starts 15 minutes before the expected arrival time
• Access ends 15 minutes after the departure time (or midnight following arrival if no departure specified)
• This buffer ensures visitors can enter slightly early or leave slightly late without issues

​

How Access is Managed

​

When Access is Granted

Nexudus grants access when:

• A contract starts: Customer receives the passes included in the plan, which grant access to configured doors
• A pass is assigned directly: Access granted during the pass validity window
• A booking is created: Access 15 minutes before booking start until booking end
• A contract includes desks/units: Immediate access to lock tags mapped to those desks (both from customer’s own contracts and, for team billing, from the paying member’s contracts)
• An active check-in: If a customer checks in with a specific pass, they maintain access to that pass’s doors even if time-limited

​

When Access is Revoked

Nexudus revokes access when:

• A contract ends or is cancelled: Customer loses the passes from that plan and any desk-based access from that contract
• A pass expires or is fully consumed: Access to those doors is removed
• A booking is cancelled or ends: Temporary resource/desk access is removed
• A desk is removed from a contract: Access to that desk’s lock tags is removed
• A customer is deactivated: All access is revoked

Synchronization: Access changes are debounced by 5 seconds to batch multiple rapid changes together. Updates typically complete within 10-15 seconds of the inventory change in Nexudus. No-access behavior: When a customer loses all access, you can configure whether to suspend their SofiaLocks account or delete it entirely (configured via SofiaLocks.NoAccessBehaviour setting).

​

Mobile App Experience

Customers use the Nexudus Passport Whitelabel app to unlock doors:

1. Install your space’s branded Nexudus Passport app (iOS or Android)
2. Sign in with the email address registered in Nexudus
3. The app obtains a SofiaLocks access token automatically
4. The app shows only doors they currently have access to based on their active passes, bookings, and desk assignments
5. Tap a door to unlock it
6. Each unlock triggers a check-in event in Nexudus (if the door is configured for presence tracking)

Note: Remote opening (unlocking doors from within the app without being physically present) is not supported for SofiaLocks. Customers must be near the door to unlock it.

​

Troubleshooting

​

Monitoring Integration Errors

Nexudus monitors your access control integration and alerts you to any issues that need attention.

​

Business Checkup Dashboard

Access control integration errors are displayed on the Business Checkup page:

1. Go to Home > Important Items in the dashboard, or
2. Navigate directly to dashboard.nexudus.com/dashboards/checkup
3. Look for the Access Control Integration tile
4. If there are errors, the tile will be displayed in red

​

What Gets Flagged

• Authentication failures: Expired credentials or invalid API tokens
• Provisioning errors: Failed attempts to create or update customer access
• Configuration issues: Missing or invalid access group/lock tag mappings
• Synchronization problems: Delays or failures in updating access permissions

Each error includes:

• The customer affected
• The nature of the problem
• When the error occurred
• Suggested actions to resolve it

​

Check-In Audit Trail

• Nexudus check-in records: Show when customers accessed the space (if doors are configured for presence tracking)
• SofiaLocks door event logs: Available in your SofiaLocks dashboard showing every unlock attempt

Note: Door events from SofiaLocks are polled every 9 minutes, so check-in records may appear with a slight delay compared to the actual door open time.

​

Security Considerations

• Access is inventory-driven — customers can only access doors if they have active inventory
• No permanent mobile credentials — access is managed by cloud rules, not device tokens
• Automatic expiry — all time-bound access (visitors, bookings) expires automatically
• Audit trail — every door open is logged with customer identity and timestamp

​

Technical Details

For developers and IT administrators

​

API Architecture

• Authentication: OAuth2 Resource Owner Password flow with username/password
• Base URL: https://api-{location_id}.jago.cloud
• Token type: Bearer token (stored in SofiaLocks.ApiToken setting)
• Credential rules endpoint: /api/v2/credentialRules
• Users endpoint: /api/v2/users
• Smart locks endpoint: /api/v2/smartLocks
• Lock tags endpoint: /api/v2/lockTags

​

Synchronization

• Access changes are debounced by 5 seconds per customer to batch rapid updates
• Distributed locking prevents race conditions in multi-server deployments
• Background task polls door events every 9 minutes for check-in tracking
• User provisioning happens on first inventory assignment (lazy creation)
• Credential rules are created/updated/deleted as inventory changes
• Access signature hashing prevents unnecessary API calls when access hasn’t changed

​

No-Access Behavior

When a customer loses all access, the system can:

• Suspend (default): Disable the user in SofiaLocks but keep the account
• Extended Suspend: Same as suspend (for compatibility)
• Delete: Remove the user from SofiaLocks entirely

Configured via SofiaLocks.NoAccessBehaviour business setting.

​

External IDs

• Customers: extId set to Nexudus coworker ID (integer)
• Visitors: extId set to NEXVIS-{visitorId} for both user and credential rule
• Credential rules: extId set to coworker ID for customer rules, NEXVIS-{visitorId} for visitor rules

​

Lock Tags vs Locks

• Locks (smart hardware) are configured for presence tracking (check-in/check-out actions)
• Lock Tags (logical groups) are used for access control and credential rules
• Inventory (passes, resources, desks) is mapped to lock tags, not locks directly
• One lock tag can represent multiple physical doors
• Multiple lock tags can be assigned to a single inventory item (comma-separated)

​

Contract-Based Desk Access

• Desk access is determined by active contracts, not direct desk assignments
• Customer receives access to desks in: coworker.ActiveContracts().SelectMany(x => x.Desks)
• For team billing (merged billing), customer also receives access to: GetPayingMember().ActiveContracts().SelectMany(x => x.Desks)
• This is checked via coworker.PaysInvoicesViaTeam() in the access update logic
• Each desk can be mapped to multiple lock tags (comma-separated lock tag IDs)

​

Visitor Time Window Calculation

• Arrival: ExpectedArrival or current UTC time if not set
• Departure: DepartureDate if set, otherwise midnight following arrival in business local time
• Buffer: ±15 minutes added to both arrival and departure
• Credential rule uses both date interval (specific dates) and time interval (00:00-23:59)

​

Business Settings Reference

Setting	Purpose
SofiaLocks.Enable	Integration enabled flag (“true”/“false”)
SofiaLocks.LocationId	SofiaLocks location identifier
SofiaLocks.Username	Admin username for authentication
SofiaLocks.Password	Admin password for authentication
SofiaLocks.ApiToken	OAuth2 bearer token (auto-generated)
SofiaLocks.GuestRoleId	Role ID for visitors (default: 5)
SofiaLocks.CompanyName	Company name sent to SofiaLocks
SofiaLocks.DefaultVisitorLockTagIds	Comma-separated lock tag IDs for non-booking visitors
SofiaLocks.NoAccessBehaviour	What to do when customer loses all access (Suspend/Delete)
SofiaLocks.LastEventDate	Last processed event timestamp (epoch millis)
SofiaLocks.Controller.Id_{lockId}.Action	Check-in action per lock (Nothing/CheckIn/CheckOut/Toggle)

​

Next Steps