API authentication

Authentication has one job: prove who is making the request before you read or change commerce data. Start by checking identity, then make the smallest real API call from your server.

The path

1. Store the token on your server

   Keep API credentials in environment variables, server secrets, or your platform’s secret manager. Do not put them in JavaScript that ships to the browser.

2. Send it as a bearer header

   Every protected API request should include Authorization: Bearer <token> and Accept: application/json.

3. Check the active identity

   Call GET /api/users/me before moving on. If this fails, the next API page will fail too.

4. Use the resolved organization

   The response includes current_organization. Catalog, checkout, and automation routes use that context for organization-owned data.

Identity endpoint

Use this as the first server-side smoke test. It proves the bearer token works and shows the organization context later API calls will inherit.

curl "https://api.plandalf.com/api/users/me" \
  -H "Authorization: Bearer $PLANDALF_API_KEY" \
  -H "Accept: application/json"

const response = await fetch("https://api.plandalf.com/api/users/me", {
  headers: {
    Authorization: `Bearer ${process.env.PLANDALF_API_KEY}`,
    Accept: "application/json",
  },
});

if (!response.ok) {
  throw new Error(`Plandalf authentication failed: ${response.status}`);
}

const identity = await response.json();

{
  "id": "usr_123",
  "email": "founder@example.com",
  "current_organization": {
    "id": "org_123",
    "name": "Example Studio",
    "timezone": "Australia/Sydney"
  }
}

{
  "message": "Unauthenticated."
}

Where credentials belong

Next calls

• Catalog API: read products and plans after the token resolves the right organization.
• Checkout SDK: pair server-side API calls with client-side checkout behavior.
• Webhooks: fan external events into Plandalf workflows.