Authentication

Every request carries a key. Send it as a Bearer token, or as the password of HTTP Basic auth for tools that only speak Basic.

Keys

You make keys in the web app at pdfdispatch.com/app/keys . An account can have as many keys as it needs; each has a name, shows when it was last used, and can be revoked on its own. All keys of an account share its plan and its usage.

A key looks like pdd_ followed by 40 letters and digits. We keep only a hash of it, so it is shown just once, when you make it. If you lose one, revoke it and make another.

Keys from a contract account also work here.

Bearer token

The usual way: an Authorization header with the word Bearer, a space and the key.

curl --header "Authorization: Bearer $PDD_KEY" \
  --form url=https://example.com --output example.pdf \
  https://api.pdfdispatch.com/v1/convert/url

HTTP Basic auth

Some tools and libraries can only do Basic auth. Put the key in the password; the user name is ignored and may be empty.

curl --user ":$PDD_KEY" \
  --form url=https://example.com --output example.pdf \
  https://api.pdfdispatch.com/v1/convert/url

Either way, the gateway checks the key and removes the header before the request goes on; the PDF engine never sees it.

Keep keys safe

• Only on servers you control. A key in a web page, a mobile or desktop app, or a public repository can be read by anyone, and every PDF they make counts on your plan. Have your front end call your own server, and make the PDF request from there. (Browsers cannot call the API directly anyway: it sends no CORS headers.)
• One key per app or server. Then a leak, or a server you retire, costs you one key, and the others keep working.
• Revoke at once when a key may have leaked. Revoking takes effect within seconds and cannot be undone; make a new key and deploy it.
• Always https://. A request to http:// is only redirected, and by then the key has already crossed the network unencrypted. Treat a key sent that way as leaked.

When the key is refused

The body is JSON, with a code, a sentence in error and a link to this documentation. All codes are in Limits and errors.