> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SofiaLocks Integration
> Connect SofiaLocks (powered by Jago Cloud) to automate door access and track customer presence in real-time.
## 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
| Feature | Supported | Notes |
| -------------------------- | ---------- | ------------------------------------------------------------ |
| **Pass-based access** | ✅ Yes | Primary access mechanism via lock tag mapping |
| **Plan-based access** | ✅ Indirect | Plans grant access through the passes they include |
| **Resource-based access** | ✅ Yes | Temporary access during bookings with 15-min lead time |
| **Desk/unit-based access** | ✅ Yes | Contract-based access with team billing support |
| **Visitor access** | ✅ Yes | Time-limited credentials with automatic expiry |
| **Booking guest access** | ✅ Yes | Non-customers can access spaces during booking windows |
| **Check-in tracking** | ✅ Yes | Door events trigger automatic check-ins (polled every 9 min) |
| **Mobile app access** | ✅ Yes | Native integration via Nexudus Passport app |
| **Remote door unlock** | ❌ No | Customers must be physically near doors to unlock |
## 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.
The authentication token is permanent and stored securely. You won't need to re-authenticate unless you change your SofiaLocks credentials.
### Step 2: Configure Presence Tracking
Presence tracking controls which door events trigger check-ins in Nexudus.
For each door, select an action:
| Action | Behavior |
| ------------- | -------------------------------------------------------- |
| **Nothing** | Door opens don't trigger check-ins (default) |
| **Check In** | Opening this door checks the customer in |
| **Check Out** | Opening this door checks the customer out |
| **Toggle** | Opening this door toggles between check-in and check-out |
Door events are polled from SofiaLocks every 9 minutes. Check-ins triggered by door opens may have a short delay.
**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)
The Nexudus Passport app integrates with SofiaLocks behind the scenes. Customers don't need to install or interact with the SofiaLocks app directly.
**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
**Check:**
* The customer has an active plan, pass, booking, or contract with desks
* The inventory (passes/resources/desks) is mapped to lock tags
* The customer has signed in to the Nexudus Passport app with their Nexudus credentials
* The customer's account is active (not deactivated)
* For team billing: If the customer is part of a team, check that the paying member has active contracts with desks mapped to lock tags
**Check:**
* The door is configured with a check-in action (not "Nothing")
* The customer has a valid pass that covers the location
* The customer's pass has not been consumed or expired
**Check:**
* The passes included in the new plan are mapped to lock tags (not the plan itself)
* The customer has received the passes from the new plan (check their active passes)
* Wait 10-15 seconds for synchronization
* Check the customer's profile in SofiaLocks directly to verify credential rules
**Check:**
* The visitor record in Nexudus has a valid visit time window
* The host's booking (if any) is mapped to lock tags
* The current time is within the visitor's access window
* The visitor has been granted access and can see the doors in the Nexudus Passport app
## 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](https://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.
Nexudus automatically retries failed operations. If errors persist, check the Business Checkup page for detailed information and follow the suggested resolution steps.
## 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
### 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
Configure how check-ins are tracked and validated
Create time passes that control access hours
Set up membership plans with door access
Manage visitor access and approvals