Integrations screen

The Integrations screen manages three product surfaces: External API clients, the Active Directory DC Agent, and the Browser extension.

Access and license boundary

The Integrations screen is shown only to the VaultPilot Owner. Admin, Auditor, and User cannot list or manage API clients or directory providers here. The license must include the Integration feature; without it, the sidebar item is disabled and the Owner is directed to License.

A read-only license blocks creating API clients and AD agents, saving directory scope, requesting a sync, running agent actions, rotating or revoking an agent token, deleting a provider, and importing AD records into a vault. Revoking an existing API client or browser-extension device stays available as a security action. Browser Extension is not licensed separately; it is part of Integration. Older extension-only licenses keep Browser Extension access but do not unlock External API or Active Directory.

What you can do here

• On External API, select read-only API permissions, assign at least one vault when required, and issue a client.
• Copy a new client secret before its timer ends; it cannot be displayed again later.
• Use the Client ledger to review active and revoked clients, permissions, vault count, last read, and who created each client.
• Filter client creation, access, and revocation events in the Audit stream, then open the original Audit Log entry.
• On Active Directory, install or repair the single agent and review sync health, the OU/group/user tree, and the agent’s capabilities.
• Manage VaultPilot sign-in scope separately from the AD users selected for vault import.
• On Browser extension, review the Chrome Web Store channel, pending and approved devices, and the archive of revoked or expired devices.

External API

Permission matrix and endpoint scope

The screen starts with the three status permissions selected. At least one permission always stays selected. Unless Vault data is selected, the vault picker is hidden and the client cannot read any vault record.

The exact addresses for each permission are listed in the Public API reference.

Vault data is the permission that needs the most care. When selected, at least one entry under Vaults in API scope is required before a client can be created. Do not select a vault for a status-only client; status permissions never decrypt vault data.

Issue a client and handle its secret

1. In the Permission matrix, select only what the consuming system needs.
2. Review the list under Endpoint scope.
3. If Vault data is selected, choose the smallest vault set needed.
4. Enter a Client name that identifies the consuming system and purpose.
5. Choose Create client.
6. Move the full Client ID and the value from Copy client secret into the consuming system’s approved secret store.

The secret stays masked on screen. When the timer ends or Clear is selected, only the one-time panel closes; the client itself remains. A lost secret cannot be shown again. After you copy the secret, VaultPilot tries to clear the clipboard shortly afterwards if the same value is still there. The browser can prevent this, and a value already pasted elsewhere cannot be taken back. Copying the Client ID does not clear the clipboard.

Client ledger, audit, and revocation

The ledger shows status, name, short Client ID, permissions, vault and log counts, last read, creator, and creation time. Copy client ID copies the full identifier. View logs selects that client in the Audit stream. For successful API use, Last read and the audit history are updated at most once every few minutes per client, not on every request. The stream shows the newest creation, access, or revocation events for the current filter; selecting a row opens the original entry in Audit Log.

After confirmation, Revoke access marks the client revoked. It stays in the ledger as evidence, cannot be reactivated, and its secret stops working. To replace a client, issue a new client with the least access needed, move the consumer to it, and then revoke the old one.

Active Directory

Data and password boundary

The VaultPilot DC Agent runs on the same network as the domain controller. It sends the DC, Base DN, bind user name, OUs, groups, users, and account state to VaultPilot. It never sends or displays the bind password or existing AD user passwords. An imported AD record holds the user’s identity and account state with an empty password field; a new password can later be set through an authorized agent action and stored in the encrypted record.

First agent record and local installation

1. Confirm the provider name; automatic sync runs every 10 minutes by default.
2. Choose Create agent record to prepare the single provider record.
3. Use Download agent script to get vaultpilot-dc-agent.ps1.
4. Copy the masked agent token separately with Copy token.
5. Use Copy command, run the service-install command in elevated PowerShell, and paste the token only into the local secure prompt.
6. When needed, use VaultPilot preflight, LDAP preflight, Status command, and Live log.

When the console is opened over HTTPS, the agent command includes the current VaultPilot certificate so the agent trusts only this server. If an enterprise CA is used, also manage its trust through the Windows certificate store or company policy. If an agent record already exists, do not create a second provider; Rotate token on the existing row produces a new token and repair command.

After Copy token or Copy command for a token, install command, or repair command, VaultPilot tries to clear the clipboard shortly afterwards if the same content is still there. Copies from VaultPilot preflight, LDAP preflight, Status command, and Live log are not cleared; remove them from the clipboard yourself.

Provider status, tree, and scopes

The provider card shows DC, Base DN, agent version, bind user name, last seen, last sync, and sync interval. Its state can be AGENT WAITING, CONNECTED, STALE, OFFLINE, or TOKEN REVOKED. A connected agent can also show SYNCING, SYNC QUEUED, or ERROR. Sync now only queues a request; follow the provider state and the Executions screen for the result.

Search directory tree searches OU, group, user, UPN, and DN. Tree, OU, Groups, and Users filter only the displayed tree. Per-user VaultPilot sign-in choices are saved immediately and kept apart from import scope. Branch and user choices for AD record import stay a draft: choose Save scope before Import selected to vault. Import requires Editor or Manager access to the active vault and a writable license.

In VaultPilot 3.0.3, a selected user already present in the same vault is updated instead of skipped, refreshing identity and account state. This works only while that vault is unlocked in an authorized browser; the agent and server cannot decrypt the record. An existing password is never replaced with blank directory data, and a user removed from scope or missing from the directory is not deleted silently. Sync can succeed while the vault update is only partly done; check each item’s result.

The Agent capabilities strip shows support for Password state, Unlock account, Require password change, Assign random password now, and Disable account. The strip does not start those actions. Account actions stay unavailable unless you are the Owner, the license is writable, the agent is CONNECTED and ready, and it reports that capability. The current agent version is 1.2.27; an older agent may sync but cannot run account actions, and syncing does not upgrade it. Built-in accounts and the bind account are always protected. Other privileged accounts need a second confirmation for manual work and a separate policy approval for automated rotation. Results appear in the Agent actions timeline.

Rotate token invalidates the old token immediately and shows the new one only in the current result panel. Under Danger actions, Revoke token stops sync until repair or re-enrollment. Delete provider removes the provider; the Windows agent then needs a new enrollment and token before it can reconnect.

Install and repair commands never contain the token value; they use -PromptAgentToken. Never add a plaintext token to the command.

Browser extension

This tab links to the Chrome Web Store as the normal installation channel; a local ZIP or Developer Mode is not the daily install path. Summary cards show last sync and approved and pending device counts. Active devices holds pending and approved devices; Archive holds revoked and expired ones.

To approve a pending request, enter the eight-character code shown in the extension popup. At least one vault must be unlocked and the license must be writable. A device row shows only the device name, the last four characters of the pairing code, and the vault-grant count; confirm the user, account, browser profile, and request through an internal channel. Approval gives the device access to the unlocked vaults; vault records and the master password are never shown in the device list. The action shown for an approved device is Revoke. Pairing and device states are covered in the Browser Extension screen guide.

Recommended workflows

Issue a status-only API client

1. Keep Vault data cleared.
2. Select only the Server status, Active Directory, and Update status permissions you need.
3. Confirm that Endpoint scope lists no vault access and that the vault picker is absent.
4. Issue the client and move its secret to the approved consumer.
5. After the first successful request, check Last read and the access event in the Audit stream. Later calls within a few minutes may not update either again.

Repair the directory agent

1. Check agent health and last seen, then check the Windows service with Status and Live log.
2. If the token is invalid or repair is required, confirm Rotate token.
3. Copy the new token separately, run the repair command in elevated PowerShell, and press Enter to keep the unchanged DC and bind settings.
4. After health returns to CONNECTED, choose Sync now; do not select scope or import records before the first sync completes.

Screen states

Before you act

• Confirm you are signed in as Owner and the license includes the Integration feature.
• Decide whether the task belongs to External API, Active Directory, or Browser extension.
• For an API client, record the consumer, business owner, needed permissions, minimum vault set, and review date.
• Before revocation, confirm the move to the replacement client or agent token is complete; do not delay an emergency revocation.
• For an AD agent change, prepare DC reachability, bind user name, elevated PowerShell, the script, and a rollback path.
• Before importing AD records, confirm the intended vault is unlocked and writable and your vault role is Editor or Manager.
• Before approving an extension device, check the row’s device name, code hint, and vault-grant count; confirm the user request and browser profile separately through an internal channel.

Safe evidence

• Safe to share: tab name, permission name, the error message, agent health, object count, and extension version and store channel.
• Keep private: full Client ID, client secret, agent ID and token, install or repair command, pairing code, device identifier, internal DC and domain, Base DN, bind user name, UPN/DN, and vault name.
• If a client secret, agent token, or pairing code was exposed, stop sharing it and revoke or rotate the affected access.
• Do not rely on cropping alone in screenshots; fully mask codes, identifiers, domains, users, file paths, commands, and correlated timestamps.

When to stop and escalate

Stop if expected clients disappear from the ledger, a second provider is about to be created for the same AD source, an agent token or client secret was pasted into the wrong system, the owner of a pairing request cannot be confirmed, the agent stays STALE, OFFLINE, or TOKEN REVOKED, or vault import includes unexpected users. Email support@vaultpilot.io with the tab, general state, redacted record ID, time, last safe step, and error text, without secret material.

Operator notes

This is not a general integration hub that grants external write access. The public API is read-only. The AD agent cannot read existing passwords; it applies supported changes only as authorized requests. The browser extension works only on approved devices and with the vaults granted to them.

Never share a screenshot or terminal transcript containing a Client ID (pmc_), client secret (pms_), agent token (pmt_), pairing code, or internal server details.

Related

• Integration API clients
• Public API reference
• Active Directory agent
• Active Directory records screen
• Browser Extension screen
• Browser extension

Back to Documentation →