Testing the API with Swagger

The API serves an interactive page at /docs (for example http://localhost:3000/docs) where you can read every endpoint and run it from the browser. It is switched off in production.

Without signing in you can try the health checks. To try GET /v1/me and the other protected endpoints you need an Auth0 tenant, which is a one-time setup.

1. Create an Auth0 tenant (once)

Use a separate tenant for development (for example pennyplan-dev). Never use the production tenant for testing.

1. Sign up at auth0.com  and create a tenant. Your Domain is shown on the dashboard, for example pennyplan-dev.us.auth0.com.

2. Register the API. Dashboard > Applications > APIs > Create API.

   • Name: PennyPlan API
   • Identifier: a unique name, for example https://api.pennyplan.dev. It does not need to be a real address. It cannot be changed later, and a trailing slash counts as part of it, so copy it exactly.
   • JWT Signing Algorithm: RS256. The API accepts nothing else.
   • Access Policy for Applications within user flow: Auth0’s default is Allow via client-grant, which blocks a sign-in application until it is explicitly authorised for this API. Either choose Allow, or after step 3 open the API’s Application Access tab and authorise the Swagger application. If you skip this, sign-in fails with an access-denied error.

3. Register the Swagger page as an application. Dashboard > Applications > Applications > Create Application, choose Single Page Web Applications. In its settings, add:

   • Allowed Callback URLs: http://localhost:3000/docs/oauth2-redirect.html
   • Allowed Web Origins: http://localhost:3000
   • Allowed Origins (CORS): http://localhost:3000

   Copy its Client ID. A single-page application has no secret to protect, so never put a client secret in any file.

4. Make sure the application can use the Username-Password-Authentication database connection (its Connections tab), so you can sign up with an email and password.

Auth0’s dashboard changes over time. If a name above does not match, look for the closest one.

2. Tell the API about it

Put these three values in the API’s .env file (never commit that file):

AUTH0_DOMAIN=pennyplan-dev.us.auth0.com
AUTH0_AUDIENCE=https://api.pennyplan.dev
AUTH0_SWAGGER_CLIENT_ID=<the Client ID from step 3>

All three are public values. The API also needs a test database in DATABASE_URL. Never point it at the live database while testing.

3. Try it

1. Start the API (pnpm dev) and open http://localhost:3000/docs.
2. Click Authorize. Under auth0, click Authorize again, sign up or log in, and accept. Alternatively, paste an access token under bearer.
3. Run GET /v1/me. The first time you sign in, your account is created.
4. Try PATCH /v1/me with { "name": "Ada", "language": "PCM" }, then try { "role": "ADMIN" } and watch it get rejected.

Your token is kept in the browser between reloads, so you do not have to sign in every time.

Things that will confuse you

Not available yet

Sign-in by phone number (one-time code) is part of the plan but is not set up. It needs an SMS provider. For now, sign in with email and password, or with Google once you add a Google connection in Auth0.