Authentication

The header

Send the key in the Authorization header of every request, as a Bearer token. Requests go to https://api.magpie-cloud.com/v1 over HTTPS only.

Authorization: Bearer $MAGPIE_API_KEY

curl https://api.magpie-cloud.com/v1/verify \
  -H "Authorization: Bearer $MAGPIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "alex.sample@examplefreight.example" }'

const res = await fetch("https://api.magpie-cloud.com/v1/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAGPIE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "alex.sample@examplefreight.example" }),
});
const data = await res.json();

import os
import requests

res = requests.post(
    "https://api.magpie-cloud.com/v1/verify",
    json={"email": "alex.sample@examplefreight.example"},
    headers={"Authorization": f"Bearer {os.environ['MAGPIE_API_KEY']}"},
    timeout=90,
)
data = res.json()

A key per app

Make a separate key for each app or service that calls the APIs, named after it. If one leaks, or a service is retired, you revoke that key and the rest keep working.

API keys are planned to be separate from the MCP keys made in a MagpieCRM workspace: neither works in the other's place.

Keeping keys safe

• Call the APIs from your server. Never put a key in a web page, a browser extension or a mobile app.
• Keep keys in environment variables or a secrets manager, not in your code or its repository.
• Don't write keys to logs or error reports.

Replacing a key

1. Make a new key for the app.
2. Deploy the app with the new key.
3. Revoke the old key once nothing uses it.

Do the same straight away if a key may have leaked.

When a key is refused

A missing, wrong or revoked key gets a 401 with the code unauthorized. Trying again won't help: check the key your app is using. See Errors.