Authentication guide

This guide covers how to wire API credentials into a real application. For the conceptual model see Authentication.

Injecting keys per environment

The only thing that should differ between dev, staging, and prod is the key value. Inject it through configuration, never code:

// Works in every environment - the key decides which one it hits.
export const meridian = new Meridian(process.env.MERIDIAN_API_KEY);

import os
from meridian import Meridian

meridian = Meridian(os.environ["MERIDIAN_API_KEY"])

MERIDIAN_API_KEY=mrnd_test_4f8e2c1a9b7d3e5f6a0c

Choosing scopes

Map each service to the minimum scope set it needs:

curl -X POST https://api.meridian.dev/v2/keys \
  -H "Authorization: Bearer $MERIDIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "svc-metrics",
    "scopes": ["events:read"],
    "expires_in_days": 90
  }'

Rotating keys without downtime

The safe rotation order - works for both dashboard and API-driven rotation:

1. Create the replacement key with identical scopes.
2. Deploy it (rolling restart, secret refresh, whatever your platform does).
3. Verify traffic on the new key - the dashboard shows per-key last-used timestamps.
4. Revoke the old key.

curl -X DELETE https://api.meridian.dev/v2/keys/key_7hF2kLm9xQ \
  -H "Authorization: Bearer $MERIDIAN_API_KEY"

Diagnosing auth failures

Every error response includes request_id - quote it when contacting support; it's the fastest way to trace a call.

Service accounts

For automation, create a dedicated workspace member marked as a service account (Settings → Members → Invite service account):

• Its keys survive staff changes - they aren't tied to a person's membership.
• Give it the minimum role needed (usually developer, live environment only).
• Audit log entries show the service account distinctly from human actions.

Next steps