Vista Instance Connection and Security

This page explains how the Vista API connects to your organization's Vista instance, who manages that connection, and why Vista user roles and security groups are critical to a successful API integration.

If you are a Vista API customer, you call REST endpoints through App Xchange. You do not connect to your Vista database directly. Understanding how that connection is established—and which security settings your organization controls—helps you avoid missing data, failed actions, and lengthy troubleshooting cycles.

How the Vista API Connects to Your Vista Instance

The Vista API is a bidirectional REST API that acts as a service layer for your organization's cloud-hosted Vista instance. API requests go to App Xchange, not to Vista directly.

At a high level, the connection works like this:

1. Your integration sends API requests to App Xchange using your subscriber code and API key.
2. App Xchange serves read requests from a cached copy of your Vista data and queues write requests (actions) for processing.
3. The Xchange Agent is a Windows service installed on your Vista environment. It provides the secure bridge between App Xchange and your Vista database. The agent discovers new, updated, and deleted Vista records on a scheduled basis (typically every hour) and keeps the App Xchange cache in sync. It also executes actions against your Vista database on your behalf.
4. Your Vista database stores the authoritative data. The API reflects that data only after the agent has read it into cache or successfully processed an action.

Because reads come from the App Xchange cache and writes are queued and processed asynchronously, the Vista API is fundamentally asynchronous. See Vista API Concepts for details on cache behavior, action processing, and endpoint patterns.

---

Who Manages the Connection to Your Vista Instance

For Trimble Construction One cloud-hosted Vista customers, the technical connection between App Xchange and your Vista instance is managed by the Vista cloud team and App Xchange, not by your API integrator or third-party vendor.

During Vista API onboarding, App Xchange coordinates with the Vista team to complete infrastructure setup on your behalf. This includes:

• Installing and configuring the Xchange Agent on your Vista cloud environment. For cloud-hosted Vista, the agent is installed on your D2 server, which connects to your D1 database server. You do not install or manage the agent yourself.
• Establishing the database connection between the Xchange Agent and your Vista database, including connection strings and company scope.
• Creating and configuring the Vista service user (SQL login) used by the agent to read and write data through the API.
• Verifying that the agent can read and write data to your Vista database with the permissions required for your enabled API endpoints.

The Getting Started Guide summarizes this handoff: App Xchange and the Vista team handle agent installation and SQL user setup. Your role during onboarding is to specify which Vista modules and endpoints you want enabled, request API keys for third-party integrators if applicable, and ensure your Vista administrators have configured application-level security correctly. This document provides substantially more detail.

What you manage as a customer:

• Purchasing and enabling the Vista API and requesting endpoint authorization for your API key(s).
• Working with your Vista administrator to configure the Vista service user's application security (security groups, datatype access, and company scope).
• Requesting changes to enabled endpoints or company scope through your customer portal or Support.

What you do not manage:

• Xchange Agent installation, hosting, or updates on your Vista cloud servers.
• SQL login creation and SQL Server role assignment on cloud-hosted Vista (handled by the Vista cloud team).
• App Xchange platform configuration, cache infrastructure, or API gateway settings.

---

---

The Vista Service User

Every Vista API connection uses a dedicated Vista service user—a special application account that represents the API integration inside Vista. This user is the identity under which the Xchange Agent reads data, writes cache updates, and executes API actions.

For Vista API integrations, the service user is typically named using the format XChange[integration target] (for example, XChangeVistaAPI or a name recommended during onboarding). In Vista, this is configured as a User Application type in Viewpoint Administration > Programs > VA User Profile.

The service user has two layers of permissions:

Both layers must be correct for the API to work. SQL roles alone are not sufficient if Vista application security restricts the service user from accessing specific datatypes or company records.

For step-by-step instructions on creating a Vista service user, see Create a Vista Service User in Trimble Help.

---

Why Vista User Roles and Security Groups Matter

Vista application security controls what data a user can see and post, independent of SQL Server permissions. The Vista API operates under the service user's Vista security context. If that user lacks access to a company, datatype, job, contract, employee, or other secured record, the API cannot retrieve or modify that data—even if the underlying SQL roles are correct.

This is one of the most common causes of API issues that appear as:

• Empty or incomplete GET responses (records exist in Vista but do not appear in the API cache).
• Action failures or partial success when creating or updating records.
• Errors referencing access, security, or missing records that the integrator can see in Vista under a different user account.
• Reports or cache data that does not match what a Vista power user sees when logged in with full access.

Security groups

Security groups are the primary mechanism for granting Vista application access. Users (including service users) are assigned to security groups in VA User Profile > Security Groups. Security groups are then granted access to secured datatypes in VA Data Security Access.

Security groups control access to predefined securable datatypes, including:

• Company
• Contract
• Job
• CM Account
• Employee
• Reference
• Location

When datatype security is enabled for your organization, every instance of a secured datatype (for example, each job or each employee) is associated with one or more security groups. A user can only access records assigned to a security group they belong to (plus the default security group configured for that datatype).

For more information, see Datatype Security and Assign Security to Secured Datatypes in Trimble Help.

Datatype security

If your organization uses datatype security, it is essential that the Vista service user is assigned to security groups with access to every datatype and company required by your API integration.

To determine whether datatype security is in use:

1. In Vista, open Viewpoint Administration > Programs > VA Data Security Setup.
2. Review the Secured column. If any datatypes are checked as secured, you must configure security group access for the service user or the integration will not be able to move the affected data.

To grant access:

1. Open Viewpoint Administration > Programs > VA User Profile.
2. Select the service user and open the Security Groups tab.
3. Assign the security groups that have access to the datatypes and companies your integration requires.
4. Use VA Data Security Access to confirm the assigned groups have Allowed access for the relevant datatypes, companies, and instances.

Work with your Vista administrator and your integration provider to identify which datatypes and companies must be accessible. The required scope depends on which API modules and endpoints you have enabled (for example, Job Cost, Accounts Payable, Payroll, Human Resources).

Company scope

App Xchange only reads and writes data for the Vista companies configured on your connection. Companies not included in the connection configuration are ignored. Confirm with your Vista administrator and during onboarding that all required company numbers are included.

SQL roles (cloud-hosted Vista)

On cloud-hosted Vista, SQL Server roles such as db_datareader, public, and VCSUsers are assigned to the service user by the Vista cloud team during connection setup. These roles allow the agent to query Vista tables at the database level.

App Xchange has limited visibility into your Vista security configuration—SQL role membership, security group assignments, and datatype access are managed inside Vista and are difficult for Support to diagnose from the platform side. If you suspect a permissions issue, work with your Vista administrator to verify the service user's setup directly in Vista (and in SQL Server for on-prem environments).

For on-premises Vista customers who manage their own SQL environment, SQL roles must be granted manually. See the on-premises section of Create a Vista Service User.

---

What Your Organization Should Verify

Before go-live—and whenever you expand API scope to new modules, companies, or datatypes—work with your Vista administrator to confirm the following:

Service user profile

• A dedicated Vista service user exists for the API integration (User Application type in VA User Profile).
• The service user is active and its password has not expired.
• The service user name matches what was provided during onboarding.

Security groups

• The service user is assigned to the correct security groups in VA User Profile > Security Groups.
• Those security groups have Allowed access in VA Data Security Access for every secured datatype your integration touches.
• Access is granted for every company the integration must read or write.
• If new jobs, contracts, employees, or other secured records are created after initial setup, verify whether they inherit the default security group or require manual assignment.

Datatype security

• If any datatypes are marked as secured in VA Data Security Setup, the service user's security groups have been explicitly granted access.
• Newly secured datatypes (added after initial setup) have been reviewed and the service user's access updated.

Company scope

• All required Vista companies are included in the API connection configuration.
• The service user has security group access across those companies.

SQL roles (confirm with Vista cloud team for cloud-hosted Vista)

• The service user has the required SQL Server roles (db_datareader, public, VCSUsers at minimum for read access).
• If your integration writes data or uses attachment endpoints, confirm any additional permissions required for those operations.

Attachments (if applicable)

• If your integration uses Document Management endpoints, the service user is authorized for the Vista Attachments database when attachments are stored separately from the primary Viewpoint database.

---

Troubleshooting Security-Related API Issues

When opening a support case for a suspected permissions issue, provide:

• The Vista service user name
• The company number(s) affected
• The API module and endpoint (for example, JC contract headers, AP invoices)
• Example record keys (KeyID or natural keys) that are visible in Vista under an admin account but missing or failing via the API
• Confirmation from your Vista administrator that security groups and datatype access have been reviewed

---

Roles and Responsibilities Summary

---

Related Documentation

• Vista API Overview
• Vista API Concepts — cache behavior, action processing, endpoints, and document management
• Getting Started Guide — onboarding and setup handoff
• Create a Vista Service User — Trimble Help
• Install the App Xchange Agent on a Vista Server — Trimble Help (reference; cloud installation is performed by the Vista team)
• Datatype Security — Trimble Help
• Assign Security to Secured Datatypes — Trimble Help

---