Authentication

Two ways to authenticate against the District Seal API. Pick the one that matches your use case.

Option 1 — API key (recommended for server-to-server)

API keys are the recommended authentication method for backend integrations that run without a browser. Each key belongs to a user account and inherits that account's plan and quota.

Creating a key

1. Sign in to your District Seal dashboard
2. Go to Developer → API keys
3. Click Create new key
4. The full secret is displayed once. Copy it and store it in a secrets manager. District Seal does not retain the plaintext.

Using the key

Send the full key as the X-API-Key header on every request:

curl https://districtseal.com/api/transactions \
  -H "X-API-Key: ds_live_abc123..."

Option 2 — Session JWT (for browser and short-lived operations)

When a user signs in to the District Seal dashboard, the server issues a JWT signed with an HS256 key. The token is valid for the duration configured on your account (default 24 hours).

Obtaining a token

curl -X POST https://districtseal.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"..."}'

# Response:
# {"token": "eyJhbGciOi...", "email": "...", "org_name": "..."}

Using the token

curl https://districtseal.com/api/transactions \
  -H "Authorization: Bearer eyJhbGciOi..."

2FA-protected accounts

If your account has TOTP two-factor authentication enabled, the login endpoint returns a challenge response instead of a token. The client must then POST the TOTP code to complete the flow and receive the actual session token.

Choosing between the two

CSRF protection

Dashboard mutation endpoints (those under /api/admin/*) require a CSRF token in addition to the JWT. Fetch it from GET /api/admin/csrf and send it as the csrf query parameter on subsequent mutation requests. Public API endpoints under /api/transactions/* do not require CSRF.

Rate limits per authentication route