Authentication

The Shepherd API uses two API keys plus a clinic identifier, all sent as request headers. There is no OAuth flow, no Bearer token, and no token-refresh dance for the primary integration path.

The three headers

Every request includes the following headers:

Header	Required	Purpose
X-Integration-Public-Key	Yes	Identifies your integration.
X-Integration-Private-Key	Yes	Proves ownership of the integration. Treat this like a password.
X-Clinic-Id	On most endpoints	The clinic UUID this request operates against. A few clinic-lookup endpoints accept calls without it; the rest require it.

Both keys must be sent on every call. The public key is not a “client ID”; both values are secret, and the private key in particular must never be embedded in mobile apps, browser code, or anywhere a third party can read it.

X-Clinic-Id is a header, not a body field

The clinic id travels as a request header, the same as your two keys. Putting a clinicId in the JSON body does nothing: the request is still rejected with 401 Missing X-Clinic-Id header. Set the X-Clinic-Id header on every clinic-scoped call. The only endpoints that accept a call without it are the clinic-lookup and group-lookup endpoints (covered below), which let you discover a clinic’s UUID before you have one to send.

How keys are issued

How you get keys depends on who you are.

Clinic accounts building on their own data. If your Shepherd account has the open API feature enabled, you can generate and manage integration keys yourself from inside Shepherd (Admin → Integrations). These are self-service. You’ll normally build against your live clinic; ask your account manager if you’d like a separate sandbox first.

Integration partners building for other clinics. The Shepherd product team issues your keys as part of integration onboarding:

1. You’ll get sandbox credentials first, scoped to a demo clinic, so you can build and test against https://demo-open-api.shepherd.vet/pav2/.
2. Production credentials are issued once your integration is reviewed and the partner clinic agrees to enable it.

Either way, read the keys from environment variables or a secrets manager; never hard-code them.

Key rotation

Rotate the private key any time you suspect exposure. Because both keys are checked on every request, the safest pattern is:

1. Request a second active key from the Shepherd team.
2. Deploy the new key alongside the old one (most clients can hot-swap an environment variable).
3. Confirm traffic is flowing under the new key.
4. Ask the Shepherd team to revoke the old key.

Build your integration so the keys are read from environment variables or a secrets manager, never hard-coded.

The per-clinic scope model

The Shepherd API is multi-tenant. A single integration key can be granted access to one clinic or many, but every request operates against exactly one clinic at a time, named by X-Clinic-Id. There is no single call that returns data across every clinic at once. To cover a clinic group, change X-Clinic-Id between requests; or, where the relevant data is shared across the group, scope a query with a clinicIds filter. See Groups and multi-site for how that works, and the Clinics endpoint for discovering the clinic UUIDs your keys can reach.

Hello world

The shortest end-to-end check is to fetch one clinic record. If the credentials are valid for at least one clinic, this returns a collection envelope with a single item. If the keys are wrong, you’ll get an HTTP 401 whose body is a JSON string explaining why.

curl

curl -X POST https://open-api.shepherd.vet/pav2/open-api-clinics \
  -H "Content-Type: application/json" \
  -H "X-Integration-Public-Key: $SHEPHERD_PUBLIC_KEY" \
  -H "X-Integration-Private-Key: $SHEPHERD_PRIVATE_KEY" \
  -H "X-Clinic-Id: $SHEPHERD_CLINIC_ID" \
  -d '{"page":1,"rpp":1}'

Python

import os, requests

resp = requests.post(
    "https://open-api.shepherd.vet/pav2/open-api-clinics",
    headers={
        "Content-Type": "application/json",
        "X-Integration-Public-Key": os.environ["SHEPHERD_PUBLIC_KEY"],
        "X-Integration-Private-Key": os.environ["SHEPHERD_PRIVATE_KEY"],
        "X-Clinic-Id": os.environ["SHEPHERD_CLINIC_ID"],
    },
    json={"page": 1, "rpp": 1},
    timeout=30,
)
resp.raise_for_status()
data = resp.json()
print(f"Total clinics visible: {data['totalRecords']}")

C#

using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-Integration-Public-Key", publicKey);
http.DefaultRequestHeaders.Add("X-Integration-Private-Key", privateKey);
http.DefaultRequestHeaders.Add("X-Clinic-Id", clinicId);

var body = JsonContent.Create(new { page = 1, rpp = 1 });
var resp = await http.PostAsync(
    "https://open-api.shepherd.vet/pav2/open-api-clinics", body);
resp.EnsureSuccessStatusCode();
var json = await resp.Content.ReadAsStringAsync();
Console.WriteLine(json);

PHP

<?php
$ch = curl_init('https://open-api.shepherd.vet/pav2/open-api-clinics');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Integration-Public-Key: ' . getenv('SHEPHERD_PUBLIC_KEY'),
        'X-Integration-Private-Key: ' . getenv('SHEPHERD_PRIVATE_KEY'),
        'X-Clinic-Id: ' . getenv('SHEPHERD_CLINIC_ID'),
    ],
    CURLOPT_POSTFIELDS => json_encode(['page' => 1, 'rpp' => 1]),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
echo "HTTP $status\n$response\n";

JavaScript

const resp = await fetch('https://open-api.shepherd.vet/pav2/open-api-clinics', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Integration-Public-Key': process.env.SHEPHERD_PUBLIC_KEY,
    'X-Integration-Private-Key': process.env.SHEPHERD_PRIVATE_KEY,
    'X-Clinic-Id': process.env.SHEPHERD_CLINIC_ID,
  },
  body: JSON.stringify({ page: 1, rpp: 1 }),
});
if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`);
const data = await resp.json();
console.log(`Total clinics visible: ${data.totalRecords}`);

If that returns 200 OK with a JSON body, you are authenticated. From here, read Conventions to learn pagination, embedding, and date filtering, then jump into the resource pages.