Authentication
Apier's consumer auth model — API keys, tiers, per-endpoint access categories, and the sandbox isolation contract.
[Cite this as: Apier.no Docs v0.1.0 — last updated 2026-06-04]
Apier uses bearer API keys for authentication. Every key is SHA-256 hashed at rest and is never logged. Keys are issued in the dashboard and shown in full exactly once — store yours securely.
Making an authenticated request
Pass your key in the Authorization header:
GET /api/v1/company/{org}/summary HTTP/1.1
Authorization: Bearer apr_test_<your_key_here>The MCP server and the quickstart examples set this header for you.
Key formats
One prefix scheme runs across the whole API, so you can tell at a glance what a token is and where it works:
| Prefix | What it is | Where it works |
|---|---|---|
apr_free_… | A free-tier key, issued by default on signup | Every endpoint; Category B at the Free-tier rate limit |
apr_test_… | An issued test-tier key | Every endpoint, against synthetic data |
apr_live_… | An issued production key | Production /api/v1/* — real filings |
apier_sandbox_test_<suffix> | The no-signup synthetic sandbox bearer | The /api/v1/sandbox/* routes only |
Issued keys (apr_…) come from your dashboard and are shown in full exactly once. The synthetic sandbox bearer needs no signup — the <suffix> (1–64 characters of [A-Za-z0-9_-], typically a crypto.randomUUID()) is a private session namespace you choose. See the quick start for the sandbox walkthrough.
Access categories
Apier endpoints fall into two categories:
| Category | Auth required | Examples |
|---|---|---|
| Category A | No — open to any caller | /api/v1/public/obligations, /api/v1/public/deadlines, /api/v1/health/agent-readiness |
| Category B | Yes — valid API key | /api/v1/company/{org}/summary, /api/v1/company/{org}/obligations, /api/v1/actions/execute |
Category A endpoints are safe to call from a browser or an unauthenticated agent to discover obligations and deadlines without exposing a key.
The sandbox and its isolation contract
The sandbox surface (/api/v1/sandbox/...) returns deterministic synthetic data and never calls a government system. It accepts the no-signup apier_sandbox_test_<suffix> bearer (and a real key too), and the boundary between sandbox and production is enforced both ways:
- A real key used on
/api/v1/sandbox/*is accepted, but the response is still mock — a sandbox request never reaches a government upstream, so nothing is ever submitted there. - The synthetic bearer is rejected on production
/api/v1/*routes with401 AUTH_INVALID_KEY— it works only on the sandbox surface.
So a misrouted call fails safe in both directions: a production key cannot accidentally file through the sandbox, and a sandbox bearer cannot reach the real API. See Going live for the switch to real filings.
Rate limits
Company-data (Category B) limits scale with your tier:
| Tier | Category B limit |
|---|---|
| Free | 30 requests / min |
| Starter | 150 requests / min |
| Professional | 300 requests / min |
| Enterprise | Unlimited |
Category A endpoints share a separate public rate limit (1 000 requests / min per IP) and are not counted against your tier quota.
Scopes
Each key carries a scopes array (default ["read:*"]). Category B endpoints declare the scope they require — for example, /api/v1/actions/execute requires read:actions. Reserved prefixes (write:, act:, delegate:) are not assignable today. The full assignable set is listed on /api/v1/capabilities.
Key rotation
You may hold up to 3 active keys at once. To rotate: generate a new key in the dashboard, update your environment variable, then revoke the old key. Because both keys are valid during the overlap, there is no downtime window.
How keys are enforced
All authentication logic lives in src/middleware/auth.ts and src/lib/auth/*. On every Category B request the key is resolved, validated against the SHA-256 hash stored in Supabase, scope-checked, and rate-limited before the handler runs.