Authentication

Send the key as a bearer token#

Every request to the API sends the key in the Authorization header:

Authorization: Bearer sf_live_...

curl https://api.switchfile.io/v1/account \
  -H "Authorization: Bearer $SWITCHFILE_API_KEY"

const res = await fetch("https://api.switchfile.io/v1/account", {
  headers: { Authorization: `Bearer ${process.env.SWITCHFILE_API_KEY}` },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log((await res.json()).email);

<?php
$ch = curl_init('https://api.switchfile.io/v1/account');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('SWITCHFILE_API_KEY')],
    CURLOPT_RETURNTRANSFER => true,
]);
echo json_decode(curl_exec($ch), true)['email'], PHP_EOL;

import os
import requests

res = requests.get(
    "https://api.switchfile.io/v1/account",
    headers={"Authorization": f"Bearer {os.environ['SWITCHFILE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()["email"])

A key that is missing or revoked returns 401 with the code UNAUTHENTICATED.

Kinds of keys#

Create and revoke live and sandbox keys in the dashboard under API keys. An account can have up to 25 active keys. The full key is shown once, when you create it. A revoked key stops working right away. Service keys are set up on request, write to [email protected].

Keep the key on your server#

The key gives full access to your account and its credits. Keep it in an environment variable or a secret store and send requests from your server. Do not put it into a public repository or into code that runs on your users' devices. If a key leaks, revoke it in the dashboard and create a new one.

Endpoints without a key#

These work without an API key:

• GET /v1/formats and GET /v2/convert/formats: the list of supported conversions
• Signed URLs that the API returns for downloads and uploads, including ZIP archives. The signature in the URL is the permission, so you can hand these URLs to a browser.
• GET /health

Coming from CloudConvert#

Jobs and tasks (/v2) read the key from the same Authorization: Bearer header as the CloudConvert API v2. Replace the CloudConvert key with a switchfile key and the base URL with https://api.switchfile.io.