Launch pricing 50% off templates until 21 Sep

Aurora API Starter README

Latest release v1.2.0 · 2026-09-07 · this is the file that ships inside the package

README Changelog Buy Aurora API Starter

Aurora API Starter

Everything between “I have an API” and “people pay me per call”, in one Phoenix app you own: workspaces and API keys, plans with hard caps or metered overage, per-second rate limits, Stripe subscriptions, a live usage dashboard, a developer portal generated from your OpenAPI file, and a site admin.

Built on Phoenix 1.8 / LiveView 1.2 and the free, MIT Aurora Meter metering core. Add Aurora Meter Pro to invoice overage through Stripe Billing Meters (docs/pro-mode.md).

Commercial template. See license.md. Not open source.

Quick start

# Postgres 16 (Docker): docker run -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:16-alpine
cp .env.example .env            # DB_PORT if not 5432; Stripe test keys when you get to billing
mix setup                        # deps, db create/migrate, assets
mix phx.server                   # http://localhost:4000
  1. Register at /users/register; the magic link lands in /dev/mailbox.
  2. Create a workspace, then an API key (use a test key while integrating).
  3. Make a request: 
curl -X POST http://localhost:4000/api/v1/echo \
  -H "Authorization: Bearer ak_test_…" \
  -H "Content-Type: application/json" \
  -d '{"text": "hello world"}' -i

Watch X-Quota-Remaining and X-RateLimit-Remaining in the response, and the usage bar move on the workspace overview.

Make yourself a site admin: mix aurora_api.admin you@example.com → /admin.

What’s inside

Area Where Notes
Accounts lib/aurora_api/accounts* Phoenix 1.8 phx.gen.auth: magic link + optional password, sudo mode, scopes
Workspaces lib/aurora_api/organizations* orgs, owner/admin/member roles, hashed invitation tokens, scope-first authorisation
Metering lib/aurora_api/metering* AuroraApi.Metering seam over Aurora Meter; the plan ladder in Metering.Plans
API keys lib/aurora_api/api_keys* SHA-256 stored, secret shown once, live/test modes, expiry, rotate, revoke
API pipeline lib/aurora_api_web/plugs/api_* ApiAuth (bearer) → ApiRateLimit (Hammer, per plan) → ApiMeter (per-action weighted quota)
Example endpoints lib/aurora_api_web/controllers/api/v1/ POST /echo (1 unit), POST /echo/analyze (5 units), GET /me
Billing lib/aurora_api/billing*, lib/aurora_api_web/stripe_handler.ex Stripe Checkout + portal, webhook-driven plan sync, optional Pro mode
Workspace UI lib/aurora_api_web/live/* overview (live usage + 14-day chart), usage (30-day charts, CSV export), keys, members, plan & billing, settings
Admin lib/aurora_api/admin.ex, live/admin_live.ex stats, workspaces with plan override, users with admin toggle
Developer portal priv/openapi.yaml, lib/aurora_api/open_api.ex /docs rendered from the spec; /openapi.{yaml,json}
Email lib/aurora_api/mailer.ex Swoosh; Resend in production, local mailbox in dev
Jobs Oban queues default, mailers, usage, aurora_meter

Make it yours

  1. Replace the example endpoint. See docs/replace-the-example-endpoint.md. In short: add a controller under AuroraApiWeb.Api.V1, plug ApiMeter (with cost: for expensive actions), add the route to the /api/v1 scope, and describe it in priv/openapi.yaml.
  2. Set your plans. Edit AuroraApi.Metering.Plans: prices, hard caps or metered allowances, per-second limits, feature flags. Pricing page, checkout, entitlements and the API headers all follow.
  3. Connect Stripe. Create one recurring price per paid plan, put the ids in .env, run stripe listen --forward-to localhost:4000/webhooks/stripe. Upgrading in the billing page now round-trips through Checkout and the webhook moves the workspace to the new plan.
  4. Brand it. lib/aurora_api_web/components/layouts.ex (nav, sidebar), page_html/home.html.heex, assets/css/app.css (daisyUI themes).
  5. Deploy. docs/deploy.md (Fly.io; Dockerfile and release scripts included).

Commands

mix precommit        # format, compile --warnings-as-errors, credo --strict, tests
mix test             # DB_PORT=… if your Postgres isn't on 5432
mix aurora_api.admin you@example.com

Environment

See .env.example. Production needs DATABASE_URL, SECRET_KEY_BASE, PHX_HOST, the Stripe variables, RESEND_API_KEY and MAIL_FROM.

Documentation

  • docs/replace-the-example-endpoint.md — shipping your own API
  • docs/metering-and-plans.md — how quotas, rate limits, costs and modes fit together
  • docs/pro-mode.md — invoicing overage with Aurora Meter Pro
  • docs/deploy.md — Fly.io deployment
  • AGENTS.md — coding conventions for humans and agents

Tests

188 tests cover the contexts, the API pipeline (401/402/422/429, weighted costs, test-key isolation), Stripe checkout and webhooks (fake client), the LiveViews and the admin. Pro-mode tests run with BILLING_MODE=pro mix test --include pro once the package is installed.