Authentication

Protected routes accept either a session cookie (browser-friendly) or an API key Bearer token (programmatic). The API tries the Bearer header first, then the session cookie.

Cookie session

Used after POST /v1/auth/register or POST /v1/auth/login.

Property	Value
Cookie name	mintea_session
Flags	HttpOnly, SameSite=Lax, Path=/
Secure	Enabled in production (and when COOKIE_SECURE is set)
TTL	7 days

Example login and authenticated request:

curl -c cookies.txt -X POST https://api.mintea.tech/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com","password":"password123"}'

curl -b cookies.txt https://api.mintea.tech/v1/auth/me

Logout clears the cookie:

curl -b cookies.txt -c cookies.txt -X POST https://api.mintea.tech/v1/auth/logout

Cross-origin browser clients must send credentials (credentials: 'include' / withCredentials) and use an allowed origin — the API reflects the request Origin and allows credentials.

API keys

Create a key while authenticated (cookie session recommended for the create call):

curl -b cookies.txt -X POST https://api.mintea.tech/v1/api-keys \
  -H 'content-type: application/json' \
  -d '{"name":"ci"}'

• Keys are returned once in the create response. Store them securely.
• Prefix: mtk_ for live keys (Fuji / Avalanche, spends credits)
• Prefix: mts_ for sandbox keys (simulated chain, 0 credits, not onchain)
• Only a SHA-256 hash of the key is stored server-side.
• Send on every protected request:

curl -H "Authorization: Bearer mtk_..." \
  https://api.mintea.tech/v1/billing/credits

# Integrator sandbox — same host, no credits, no public chain
curl -b cookies.txt -X POST https://api.mintea.tech/v1/api-keys \
  -H 'content-type: application/json' \
  -d '{"name":"ci","environment":"sandbox"}'

curl -H "Authorization: Bearer mts_..." \
  https://api.mintea.tech/v1/chains

List and revoke keys:

curl -b cookies.txt https://api.mintea.tech/v1/api-keys
curl -b cookies.txt -X DELETE https://api.mintea.tech/v1/api-keys/<id>

Invite-gated registration

POST /v1/auth/register requires a valid inviteCode. Invalid or already-consumed invites fail with a client error. Login does not require an invite.

Auth failures

Missing or invalid credentials return 401 with code unauthorized. See Errors.