Skip to main content
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.
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.

​
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.
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.
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.
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:
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.
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.

​
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. 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

1

Default to private

If the documents belong to a customer, a matter, or anyone other than you, keep public at its default of false.
2

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.
3

Use public only for genuinely public content

Demos, samples and marketing material. Not client documents.
4

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.

Viewing and sharing results

Embedding comparisons in your app

Generating a new API key

Creating a comparison