> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velatir.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bring Your Own Certificate

> Use your organisation's certificate authority as the authority Velatir uses to inspect AI traffic

## Overview

By default Velatir generates a unique certificate authority on each device. Organisations that already run an internal CA can supply their own instead, so managed devices do not need to trust a new root. For pilots, the default Velatir CA is the simpler choice.

## What to Provide

A **PFX (PKCS#12)** bundle containing the CA certificate, its private key, and any intermediates needed to chain to a root your devices trust. The private key stays on the device and never leaves it.

<Note>
  The certificate must be a CA (`keyUsage` including `keyCertSign` and an appropriate `basicConstraints` extension). A leaf certificate will not work, because Velatir issues per-host certificates from it.
</Note>

## Single-Device Setup

For evaluation on one device, use the CLI:

```bash theme={null}
velatir set-ca --path /path/to/internal-ca.pfx --password 'your-pfx-password'
```

Verify the change took effect. `get-config` lists the active certificate fingerprint; `status` confirms the new authority is in use.

```bash theme={null}
velatir get-config
velatir status
```

## Organisation-Wide Setup

Deploy the PFX bundle from your MDM platform first, then deploy the desktop client with the bundle path in the install command.

### Windows (Intune)

1. Deploy the PFX to a known path (for example, `C:\ProgramData\Velatir\byo-ca.pfx`) using an Intune file policy.
2. Point the MSI at it:

   ```
   /qn INGEST_KEY="vltr_..." VELATIR_BYO_CA_PATH="C:\ProgramData\Velatir\byo-ca.pfx" VELATIR_BYO_CA_PASSWORD="<password>"
   ```

### macOS (Jamf Pro)

1. Deploy the PFX via a Jamf file payload (for example, `/Library/Application Support/Velatir/byo-ca.pfx`).
2. In the ingest-key staging script, also call:

   ```bash theme={null}
   /usr/local/bin/velatir set-ca \
     --path "/Library/Application Support/Velatir/byo-ca.pfx" \
     --password "<password>"
   ```

See [Enterprise deployment](/desktop-app/enterprise-deployment) for the full Intune and Jamf Pro flow.

## Rotating the Certificate Authority

Deploy the new PFX to the same path and redeploy the install command, or rerun `set-ca`. For lower risk, roll out group by group:

1. Stage the new CA in a small device group.
2. Confirm `velatir status` shows the new fingerprint and interactions still reach the dashboard.
3. Expand the rollout.

Rotation restarts capture, so one in-flight interaction may produce a single failed trace. Plan rotations during low-activity periods if that matters.

## Removing the Custom Certificate Authority

To revert to the Velatir-issued CA:

```bash theme={null}
velatir set-ca --path '' --password ''
```

## Verification

After installing or rotating, confirm supported applications still see a valid certificate chain:

```bash theme={null}
velatir logs --host -f
```

Trigger an interaction in a supported AI application; the log should show a successful connection on the new authority. If applications report certificate errors, see [Troubleshooting](/desktop-app/troubleshooting#certificates).

## Next Steps

<CardGroup cols={2}>
  <Card title="Enterprise deployment" icon="building" href="/desktop-app/enterprise-deployment">
    The Intune and Jamf Pro flows that wrap bring-your-own-CA distribution.
  </Card>

  <Card title="Permissions" icon="shield-check" href="/desktop-app/permissions">
    How the desktop client handles certificates at install time.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/desktop-app/cli">
    Detail on the `set-ca` and `get-config` commands.
  </Card>

  <Card title="Troubleshooting" icon="life-buoy" href="/desktop-app/troubleshooting">
    Diagnose certificate trust issues after a rotation.
  </Card>
</CardGroup>