---
name: python-flask-api-boilerplate
description: "Scaffolds a Flask REST API with an app factory, optional blueprints, your chosen ORM and auth layer, JSON error handlers, and CORS configured exactly as tight as you want it. Use when a new Flask API needs an app factory scaffold with blueprints, an ORM, an auth decorator, JSON error handlers, and CORS set up from day one. Do not use for choosing between Flask and FastAPI, or generating endpoints from an endpoint list and data models. Related topics: coding, python, flask."
---

# Python Flask API Boilerplate

Scaffolds a Flask REST API with an app factory, optional blueprints, your chosen ORM and auth layer, JSON error handlers, and CORS configured exactly as tight as you want it.

## When to use

Use this skill when a new Flask API needs an app factory scaffold with blueprints, an ORM, an auth decorator, JSON error handlers, and CORS set up from day one. Do not use it for choosing between Flask and FastAPI, or generating endpoints from an endpoint list and data models.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Create the app factory with a Config and TestConfig read from environment variables so tests and production build the app the same way.
3. Add the health and example routes as blueprint packages or a single module according to the toggle.
4. Initialize the chosen ORM as a factory extension, or a per-request connection helper for raw SQL.
5. Implement the chosen auth as a decorator applied to the example resource, with its login route where one is needed.
6. Register uniform JSON error handlers, configure CORS from the origin inputs, and output the tree plus every file with requirements and run command.

## Inputs

- **Enable Blueprint routing** (choose one: Yes, No)
- **Database ORM** (choose one: SQLAlchemy, MongoEngine, Raw SQL, None)
- **Authentication** (choose one: JWT, Session, API Key, None)
- **Allow all origins (wildcard)** (choose one: Yes, No)
- **Specific origin** (free text, e.g. "http://localhost:3000")

## Output

A directory tree, then one fenced block per file headed by its path (app factory, config, routes or blueprints, extensions, auth, error handlers, requirements.txt, .env.example), ending with the run command.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Python Flask API Boilerplate

Create a production-ready Flask REST API scaffold.

- Enable Blueprint routing: {{Enable Blueprint routing}}
- Database ORM: {{Database ORM}}
- Authentication: {{Authentication}}
- Allow all origins (wildcard): {{Allow all origins (wildcard)}}
- Specific origin: {{Specific origin}}

Build around an application factory (create_app) so tests and the WSGI server construct the app the same way, with configuration read from environment variables through a Config class and a separate TestConfig. With blueprints on, put a health endpoint and an example resource in their own blueprint packages registered in the factory; with blueprints off, keep the routes in a single module. Wire the chosen ORM as an extension initialized in the factory (SQLAlchemy with Flask-SQLAlchemy and a migrations note, MongoEngine with its connect call, raw SQL with a per-request connection helper that closes on teardown). Add the chosen auth as a decorator the example resource uses: JWT with a verify step and a login route that issues tokens, Session with login and logout, API Key read from a header and compared in constant time. Register JSON error handlers for 400, 401, 404, 405, and 500 that return the same shape every time. Configure CORS from the inputs: all origins only when the toggle says so, otherwise just the given origin, with credentials off unless Session auth is chosen. Include requirements.txt, a .env.example, and a run command. Return the project as a directory tree followed by one fenced python or text block per file headed by its path.

## Pitfalls

- Allowing all origins with credentials enabled, which browsers reject and which would expose session cookies if they did not.
- Creating the app at import time instead of in a factory, so tests cannot build an isolated instance.
- Comparing an API key with == rather than a constant-time compare, which leaks timing information.
