Integrations
The One Visitor integrates with other products in The One Stack and exposes integration endpoints for external systems.
Hub (Identity and Permissions)
Integration Type: Native — built into every Visitor session
Every Visitor user authenticates through Hub SSO. There is no separate Visitor login.
What Hub provides to Visitor:
- User identity (name, email, role)
- Org membership and tenant association
- Session management (8-hour TTL, Hub-managed cookies)
- JTI replay prevention for SSO tokens (each login token is single-use)
Data flow:
- User navigates to
app.theonevisitor.app - Visitor redirects to Hub SSO (
my.theonestack.com/login?redirect=visitor) - Hub validates identity and issues a signed token
- Visitor validates the token and creates a session
If this is misconfigured:
- Users land on the login page and cannot sign in
- "Token already used" errors indicate JTI replay (user refreshed the SSO redirect URL)
- "No account found" errors indicate the user does not exist in your Hub org
Hub — Permissions
Integration Type: Native — permission checks on every protected API call
Visitor registers 11 granular permissions with Hub. These control what each user can do in Visitor:
| Permission | Controls |
|---|---|
visitor.visitors.view | View visitor records and log |
visitor.visitors.checkin | Create new check-ins |
visitor.visitors.checkout | Check out visitors |
visitor.preregister.manage | Create and manage pre-registrations |
visitor.hosts.view | View the host directory |
visitor.hosts.manage | Manage who appears in the host directory |
visitor.badges.manage | Add, assign, return, and retire badges |
visitor.reports.view | View the reports page (future feature) |
visitor.reports.export | Export visitor data to CSV |
visitor.locations.manage | Create and configure locations |
visitor.admin.settings | Configure tenant-level Visitor settings |
visitor.admin.kiosk | Pair and manage kiosk displays |
Permissions are assigned per user in Hub → Users → [user] → Permissions → Visitor.
If this is misconfigured:
- Users see "Access Denied" errors on specific pages or actions
- An admin with no
visitor.admin.kioskpermission cannot access the Displays page
Hub — Billing
Integration Type: Automatic — daily background timer
Each day at 00:58 UTC, Visitor reports the count of active locations for each tenant to Hub Billing. This usage metric drives subscription billing — you are billed per active location per month.
An active location is any location with at least one check-in in the current calendar month.
Data flow:
- Visitor background function counts active locations per tenant
- Reports to Hub Billing API (
POST /api/hub/billing/usage/report) - Authenticated with
BUS_INTEGRATION_KEY
If this is misconfigured:
- Billing shows $0 usage despite active locations
- Check Hub Billing → Usage to see if reports are arriving
Hub — Global Search
Integration Type: Integration key — search queries routed via Bus
Visitor is registered as a search provider. When a user searches in the Hub Bar (across all products), Visitor returns matching visitor names and location names.
Endpoint: GET /api/search?q=...&tenant_id=...
Auth: X-Integration-Key header
Results returned:
- Visitor records (name, company, status, location)
- Location records (name, address, type)
If this is misconfigured:
- Visitor results don't appear in Hub search
- Verify
INTEGRATION_KEYenvironment variable matches the key registered with Hub
The One Bus (Event Mesh)
Integration Type: Event emission and webhook reception
Visitor emits events to the Bus and can receive webhook events from other products.
Events emitted by Visitor:
| Event | When |
|---|---|
visitor.checked_in | Visitor checks in (staff or kiosk) |
visitor.checked_out | Visitor checks out |
auth.hub_sso_login | User signs in via Hub SSO |
auth.login_failed | SSO login attempt fails |
Other products can subscribe to visitor.checked_in to trigger downstream workflows — for example, The One Security could flag a checked-in visitor against a threat intelligence list.
Inbound webhook endpoint: POST /api/integration/webhook
Auth: X-Integration-Key header
This endpoint receives events from other products and logs them to the audit trail. Automated responses to inbound events (e.g., auto-deny a visitor flagged by Security) are a planned future feature.
If this is misconfigured:
- Downstream products don't receive visitor events
- Verify
BUS_SDK_KEYenvironment variable is set correctly
The One Security
Integration Type: Planned — event-driven
The One Security will integrate with Visitor to screen visitors against threat intelligence at check-in. When a check-in event fires, Security evaluates the visitor's name, email, and company against known threat indicators and can flag or auto-deny the visit.
This integration is planned for a future release. The data fields (ai_risk_score, ai_risk_notes) exist on visitor records today to support this when it ships.
The One Legal
Integration Type: Planned — document storage
When digital NDA signing is implemented (planned), signed NDA documents will be stored in The One Legal vault for long-term retention and legal defensibility. Legal integration will be configured in Visitor's Admin Settings.
External Systems (Webhook API)
Visitor exposes integration endpoints for external systems:
| Endpoint | Description |
|---|---|
GET /api/integration/visitors-today | Export today's visitors for all tenants |
GET /api/integration/locations | Export location list |
POST /api/integration/webhook | Receive inbound webhook events |
Auth: All integration endpoints require the X-Integration-Key header.
These endpoints support integration with:
- Physical access control systems (door controllers, turnstiles)
- Building management systems
- SIEM/SOAR platforms (for security event correlation)
- External compliance reporting tools
Contact support to obtain an integration key for external system access.