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

# Private and public comparisons

> Comparisons are private by default. This article explains what that means, how signed viewer URLs authorise access, and when a public comparison is the right choice.

Every comparison you create through the Draftable API is **private by default**. This article explains what that means in practice and how to let the right people see a comparison without exposing your credentials.

## The two modes

The `public` parameter you set when creating a comparison decides which mode applies.

|                 | Private (default)                                  | Public                                       |
| :-------------- | :------------------------------------------------- | :------------------------------------------- |
| `public` value  | `false`                                            | `true`                                       |
| Who can view it | Only someone holding a valid **signed** viewer URL | Anyone with the viewer URL                   |
| Access expires  | Yes, at a time you choose                          | No                                           |
| Right for       | Client documents, contracts, anything confidential | Public samples, demos, non-sensitive content |

<Warning>
  A public comparison URL is not guessable, but it is not protected either. Anyone who obtains the link, including by forwarding, can open it indefinitely. Only use `public=true` for content you are content to have seen by anyone who gets hold of the URL.
</Warning>

## How private comparisons are authorised

You cannot simply hand a user your viewer URL, because a private comparison requires proof that the request is legitimate. That proof is a **signature**, and it is added to the viewer URL as two query parameters.

```
https://api.draftable.com/v1/comparisons/viewer/{account_id}/{identifier}?valid_until={timestamp}&signature={signature}
```

| Parameter     | What it is                                                                                     |
| :------------ | :--------------------------------------------------------------------------------------------- |
| `valid_until` | A UNIX timestamp, in seconds, after which the link stops working                               |
| `signature`   | An HMAC derived from your account ID, auth token, the comparison identifier, and `valid_until` |

The signature confirms the URL was issued by you and has not been tampered with. Critically, **your auth token is never revealed in the process** — it is used as the secret key to compute the signature, but it does not appear in the URL.

<Note>
  This is the whole point of signed URLs. Your user gets time-limited access to exactly one comparison, and learns nothing that would let them access any other comparison or make API calls on your behalf.
</Note>

### What happens when a link expires

Anyone opening an expired viewer URL cannot see the comparison.

Someone who **already has it open** keeps seeing it until they refresh or navigate away. Expiry controls new access, not an already-loaded page, so do not rely on it to revoke a session already in progress.

## Generating a signed URL

The client libraries do this for you, and this is the recommended route:

```python theme={null}
url = client.comparisons.signed_viewer_url(
    identifier,
    valid_until=timedelta(minutes=30),
)
```

```javascript theme={null}
const url = client.signedViewerURL(identifier, 30 * 60, false);
```

```csharp theme={null}
var url = comparisons.SignedViewerURL(comparison.Identifier);
```

If you implement signing yourself, compute an HMAC-SHA256 over the account ID, comparison identifier and `valid_until` value, keyed with your auth token, and hex encode the result. An incorrect signature produces a link the viewer rejects.

<Warning>
  Your auth token is the signing key. **Resetting your auth token invalidates every signed URL you have already issued.** Factor this in before rotating a token, especially if you have emailed links that people have not yet opened. See [Generating a new API key](/hc/en-us/articles/Draftable-API-generating-a-new-api-key).
</Warning>

## Choosing an expiry

Keep `valid_until` as short as the workflow allows. The client libraries default to **30 minutes**, which suits the common case of generating a link at the moment a user clicks through.

| Situation                                    | Suggested window                                                                          |
| :------------------------------------------- | :---------------------------------------------------------------------------------------- |
| User clicks through in your app immediately  | Minutes                                                                                   |
| Link emailed for the recipient to open later | Hours to days                                                                             |
| Long-lived reference                         | Reconsider. A public comparison, or regenerating links on demand, is usually a better fit |

Generating a fresh signed URL each time someone requests access is cheap, and almost always better than issuing one long-lived link.

## Viewing your own private comparisons

While you are **signed in** to your Draftable account, you can open private comparisons made with your **test** credentials without signing the URL at all. This is a convenience for development.

It applies to test comparisons only. Private comparisons made with your live credentials always require a signed URL, even while you are signed in.

## Deciding which to use

<Steps>
  <Step title="Default to private">
    If the documents belong to a customer, a matter, or anyone other than you, keep `public` at its default of `false`.
  </Step>

  <Step title="Generate signed URLs at the point of access">
    Build the URL when a user asks to view the comparison, with a short expiry, rather than storing long-lived links.
  </Step>

  <Step title="Use public only for genuinely public content">
    Demos, samples and marketing material. Not client documents.
  </Step>

  <Step title="Never hand out your auth token">
    If you find yourself wanting to give a user credentials so they can view a comparison, a signed URL is the answer instead.
  </Step>
</Steps>

## Related articles

<CardGroup>
  <Card title="Viewing and sharing results" icon="eye" href="/hc/en-us/articles/Draftable-API-viewing-and-sharing-results" iconType="solid" horizontal />

  <Card title="Embedding comparisons in your app" icon="code" href="/hc/en-us/articles/Draftable-API-embedding-comparisons" iconType="solid" horizontal />

  <Card title="Generating a new API key" icon="key" href="/hc/en-us/articles/Draftable-API-generating-a-new-api-key" iconType="solid" horizontal />

  <Card title="Creating a comparison" icon="file-import" href="/hc/en-us/articles/Draftable-API-creating-a-comparison" iconType="solid" horizontal />
</CardGroup>