Authenticating with the Draftable API

How Draftable API credentials work, how to send them, where to find them, and how to keep them safe.

Every request to the Draftable API is authenticated. This article covers what your credentials are, how to send them, and how to look after them.

Your credentials

A Draftable API account is issued two values:

Credential	What it is	Where it is used
Account ID	A short public identifier for your account	In viewer URLs, and when signing them
Auth token	A 32-character secret	In the Authorization header on every API request

Find both at api.draftable.com/account/credentials.

The auth token is a secret. Anyone holding it can create, read and delete comparisons on your account. Never commit it to source control, never expose it in client-side code, and never include it in a URL you give to an end user.

You will see two credential sets, test and production. They are functionally identical and exist to separate your development traffic from your live traffic. See Test and production accounts.

Making an authenticated request

Send the auth token in an Authorization header using the Token scheme:

Authorization: Token YOUR_AUTH_TOKEN

The API base URL is:

https://api.draftable.com/v1

A complete request:

curl https://api.draftable.com/v1/comparisons \
  -H "Authorization: Token YOUR_AUTH_TOKEN"

Only the auth token goes in the header. The account ID is not part of the Authorization value. The account ID is used separately, in viewer URLs and when generating viewer URL signatures.

With a client library

The client libraries take both values and handle the header for you:

import draftable
client = draftable.Client(ACCOUNT_ID, AUTH_TOKEN)

const draftable = require('draftable-compare-api');
const client = draftable.client(ACCOUNT_ID, AUTH_TOKEN);

var client = new Draftable.CompareAPI.Client(accountId, authToken);

Storing credentials safely

1. Keep credentials out of your codebase

   Load them from environment variables or a secrets manager. The Python command line tool, for example, reads DR_ACCOUNT and DR_TOKEN.

2. Call the API from your server, never the browser

   A comparison must be created by your backend. If your front end holds the auth token, anyone using your application can read it.

3. Use separate credentials per environment

   Test credentials for development and CI, production credentials for live traffic.

4. Give users signed viewer URLs, not credentials

   Signed viewer URLs let a user open one specific comparison for a limited time without ever seeing your auth token. This is the intended way to expose a comparison to an end user.

If a token is exposed

Reset it. You can do this yourself from your account, without contacting support. See Generating a new API key for the procedure and what to prepare first.

Treat an exposed production token as an incident. Resetting invalidates the old token immediately, so have your configuration change ready to deploy at the same time.

Resetting a token also invalidates every signed viewer URL generated with it, because the token is the signing secret. Any links already in circulation will stop working.

Your account ID cannot be changed. It is bound to your account and is deliberately public, appearing in viewer URLs. Only the auth token is a secret, and only the auth token can be reset.

Securing the account itself

The auth token protects API requests. Your Draftable account, where you view credentials, usage and account settings, is protected by your account password and can additionally be protected with multi-factor authentication.

These are separate. Enabling MFA does not change how API requests authenticate, and does not require any change to your integration. See Multi-factor authentication for your Draftable API account.

Troubleshooting

401 Unauthorized

The auth token is missing, malformed or incorrect. Check that the header reads Authorization: Token YOUR_AUTH_TOKEN, with a single space after Token and no quotes around the value. Confirm you have not accidentally used the account ID in place of the token.

I can authenticate, but I cannot see a comparison I know exists

Comparisons are visible only to the credential set that created them. If the comparison was created with test credentials, you must authenticate with test credentials to see it.

My signed viewer URLs stopped working

Signed URLs are signed with the auth token. If the token has been reset, previously generated signatures are no longer valid. Generate fresh URLs.

Related articles

Getting started with the Draftable API

Test and production accounts

Multi-factor authentication