Authentication and API keys

Every API call except GET /health is authenticated with an API key sent in the Authorization header:

Authorization: Bearer ds_live_xxxxxxxxxxxxxxxx

Keys start with ds_live_. A request without a key, or with a revoked or unknown key, is refused with 401.

Create a key

The easiest way is the dashboard: sign in at https://api.docslice.app/app, open API keys, give the key a name and press Create key. You can also create a key with the API:

Create an API key

curl -s https://api.docslice.app/v1/api-keys \
  -H "Authorization: Bearer $DOCSLICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-pipeline"}'

import json
import os
import requests

response = requests.post(
    "https://api.docslice.app/v1/api-keys",
    headers={"Authorization": f"Bearer {os.environ['DOCSLICE_API_KEY']}"},
    json={"name": "ci-pipeline"},
    timeout=30,
)
print(json.dumps(response.json(), indent=2))

fetch("https://api.docslice.app/v1/api-keys", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DOCSLICE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "ci-pipeline" }),
})
  .then((response) => response.json())
  .then((data) => console.log(JSON.stringify(data, null, 2)));

<?php
$curl = curl_init('https://api.docslice.app/v1/api-keys');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('DOCSLICE_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['name' => 'ci-pipeline']),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
echo curl_exec($curl);
curl_close($curl);

The dashboard allows up to 10 active keys per account. Give each application its own key (for example ci-pipeline or n8n-production) so you can revoke one without touching the others.

List your keys

The list shows the name, the first characters of each key (key_prefix), when it was created and when it was last used. It never shows the full key.

List your active API keys

curl -s https://api.docslice.app/v1/api-keys \
  -H "Authorization: Bearer $DOCSLICE_API_KEY"

import json
import os
import requests

response = requests.get(
    "https://api.docslice.app/v1/api-keys",
    headers={"Authorization": f"Bearer {os.environ['DOCSLICE_API_KEY']}"},
    timeout=30,
)
print(json.dumps(response.json(), indent=2))

fetch("https://api.docslice.app/v1/api-keys", {
  headers: { Authorization: `Bearer ${process.env.DOCSLICE_API_KEY}` },
})
  .then((response) => response.json())
  .then((data) => console.log(JSON.stringify(data, null, 2)));

<?php
$curl = curl_init('https://api.docslice.app/v1/api-keys');
curl_setopt_array($curl, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('DOCSLICE_API_KEY')],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
echo curl_exec($curl);
curl_close($curl);

Revoke a key

Revoke a key as soon as it may have leaked, and when an application no longer needs it. Revoked keys stop working immediately. You can revoke from the dashboard, or with the API using the id from the list:

Revoke an API key

# KEY_ID is the "id" of a key listed by GET /v1/api-keys
curl -s -X DELETE "https://api.docslice.app/v1/api-keys/$KEY_ID" \
  -H "Authorization: Bearer $DOCSLICE_API_KEY"

import json
import os
import requests

key_id = os.environ["KEY_ID"]  # the "id" of a key listed by GET /v1/api-keys
response = requests.delete(
    f"https://api.docslice.app/v1/api-keys/{key_id}",
    headers={"Authorization": f"Bearer {os.environ['DOCSLICE_API_KEY']}"},
    timeout=30,
)
print(json.dumps(response.json(), indent=2))

const keyId = process.env.KEY_ID; // the "id" of a key listed by GET /v1/api-keys

fetch(`https://api.docslice.app/v1/api-keys/${keyId}`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.DOCSLICE_API_KEY}` },
})
  .then((response) => response.json())
  .then((data) => console.log(JSON.stringify(data, null, 2)));

<?php
$keyId = getenv('KEY_ID'); // the "id" of a key listed by GET /v1/api-keys
$curl = curl_init("https://api.docslice.app/v1/api-keys/$keyId");
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('DOCSLICE_API_KEY')],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
echo curl_exec($curl);
curl_close($curl);

Keep your key safe

Read it from an environment variable or a secret manager. The examples in this documentation use DOCSLICE_API_KEY.
Never put it in code that runs in a browser or a mobile app, and never commit it to a repository. Call DocSlice from your server.
Use one key per application and rotate keys from time to time: create the new one, deploy it, then revoke the old one.
Do not paste a key into a support message. If you think a key has been exposed, revoke it.