# Papermark

> Connect your Papermark team to Tidal Control with a read-only API token, so compliance tests read how your shared documents are protected. Metadata only.

Source: https://tidalcontrol.com/docs/integrations/papermark

Tidal Control's Papermark integration reads the configuration of your Papermark team for compliance purposes. It authenticates with a bearer API token against the Papermark API (`https://api.papermark.com`), and covers how your shared documents and data rooms are protected, and who has been viewing them.

## What this integration monitors

- **Share links:** Whether links require an email, a password or a verified domain, and whether they expire
- **Data rooms:** Access configuration for grouped document collections
- **Documents:** The inventory published through your team
- **Viewers:** Who opened a link, and when
- **View events:** Access history behind each shared link

## Requirements

- Super User role in Tidal Control
- A Papermark team, on Papermark Cloud or self-hosted
- Permission to create API keys in team settings

## Configuration step-by-step plan

We'll create a **read-only API key** in Papermark, then add the connection in Tidal Control.

**Configuration steps:**

1. **Create a read-only API key**
2. **Configure the integration in Tidal Control**

## Step 1: Create a read-only API key

- Sign in to [Papermark](https://www.papermark.com)
- Open **General Settings → API Keys**
- Click **Create API Key** and select **Read Only**
- Grant all five read scopes:

<table>
<thead>
<tr><th>Scope</th><th>Covers</th></tr>
</thead>
<tbody>
<tr><td><code>links.read</code></td><td>Share links and their protection settings</td></tr>
<tr><td><code>datarooms.read</code></td><td>Data rooms</td></tr>
<tr><td><code>documents.read</code></td><td>Documents</td></tr>
<tr><td><code>visitors.read</code></td><td>Viewers</td></tr>
<tr><td><code>analytics.read</code></td><td>View events per link</td></tr>
</tbody>
</table>

- **Copy the token** (`pm_live_...`) immediately: it is shown only once

> **warning:**

**`analytics.read` is easy to miss.** View events come from the link views endpoint, which Papermark guards with `analytics.read` rather than `links.read`. Without it, link and document checks work while access history stays empty.

## Step 2: Configure the integration in Tidal Control

- Go to **Settings → Integrations** in Tidal Control
- Click the **plus icon** next to **Papermark**
- Fill in the configuration:
  - **Name:** A descriptive name, for example `Papermark`
  - **API token:** The `pm_live_...` token from step 1
- Click **"Create"** to save the integration

## Configuration fields explained

The integration dialog asks for the following values:

**Name:**
- A descriptive name for this connection
- For example: `Papermark`

**API token:**
- The read-only token from step 1
- Required, and stored as a secret
- The token identifies its own team, so there is nothing else to configure

## Verification

The integration is working when all of the following are true:

- Settings → Integrations shows Papermark under **Configured Integrations**
- Papermark tests are available in the Tests section
- Test refresh delivers results without authentication errors

## Frequently asked questions

**Does this work with a self-hosted Papermark?**
Yes. A self-hosted deployment serves the same API, and the same read-only token applies.

**Does Tidal Control read the documents themselves?**
No. It reads metadata and configuration: which links exist, how they are protected, and who viewed them. Document contents are never fetched.

**Why does the integration need viewer data?**
Because a share link with no protection is only a finding once you can see it was actually opened. Viewer and view records turn a weak setting into evidence of exposure.

## Common problems

**"API Token is required"**
- The field is empty, or the token was not copied at creation. Create a new key

**Link and document checks work but access history is empty**
- The key is missing `analytics.read`. Create a new key with all five scopes

**Authentication fails after a key rotation**
- Papermark tokens are not reused. Paste the new `pm_live_...` value into the integration

### Still can't figure it out?

Send an email to support@tidalcontrol.com, and we'll get back to you as soon as possible.

> **info:**

**Gather support info:** Note which browser you're using, exact error messages, and which steps you've already tried. This speeds up the solution considerably.