Tutorials › Metals API

Metals Simple Deploy · Metals API

The Metals API: Endpoints, Authentication, and Structure

metals_api/ is a Flask application that serves the metals catalog — elements, alloys, alloy compositions, and coins — as JSON over HTTP. Every endpoint now requires a logged-in user, and creating, changing, or deleting data is restricted to accounts with the Admin role. Codey will cover this app in three parts: what the endpoints actually do, how the login system works (including a full walkthrough in Insomnia), and how the code itself is organized.

Codey the Sr Developer, standing with a pointer, ready to walk through the guide
Folder → metals_api/ Framework → Flask Login tokens → JWT (JSON Web Tokens) Password storage → Argon2id Roles → Admin, Customer Runs as → a container, served by Gunicorn

Three sections start here

Each section stands on its own, but they build on each other in this order: first what the API does, then how you prove who you are to it, then how the code behind it all is put together.

Codey typing on a laptop
three sections, one app

Section 1

The API Endpoints

Every resource the API exposes — elements, alloys, alloy elements, coins — the HTTP methods and paths for each, what a request body looks like, and how errors are reported.

RESTJSONFlask Blueprints

Section 2

Authentication with JWT

What a JWT actually is, how this API issues and checks one, and a full step-by-step walkthrough in Insomnia: register or log in, copy the token, and attach it to every other request.

JWTBearer tokensInsomnia

Section 3

File Structure

How metals_api/ is organized — routes, services, repositories, models, and DTOs — and how a single request travels through all of them.

Layered architectureSQLAlchemy

The shape of every request the big picture

Whichever endpoint you call, the request passes through the same two checks before any business logic runs: are you logged in at all, and if this is a write, are you an Admin? Both checks live in metals_api/auth.py as small decorators reused across every route file.

Codey pointing to the right
same two gates, every route
Read endpointsGET

Require @require_auth only — any logged-in user, Admin or Customer, can look things up.

Write endpointsPOST, PUT, DELETE

Require @require_auth and @require_roles("Admin") — logged in isn't enough; the token's roles must include Admin.

Pick a section to start go deeper

Section 1 of 3

The API Endpoints

Every resource, method, path, and request body.

 Section 2 of 3

Authentication with JWT

What a JWT is, and a full Insomnia walkthrough.

 Section 3 of 3

File Structure

Routes, services, repositories, models, and DTOs.
Codey giving a thumbs up

New here? Start with the endpoints, then authentication — you'll need a token from Section 2 to actually try any of the write endpoints from Section 1.