Authentication

ModelFold uses two independent credential systems:

Caller	API	Credential	Header
Your backend	/v1 gateway	API key (mf- prefix)	Authorization: Bearer mf-...
Console frontend	/api/*	Session token (JWT)	Authorization: Bearer <token>

Model calls require an API key. You do not need a session token.

Call models with an API key

Set the Authorization header to Bearer <key>:

curl -X POST "https://modelfold.ai/v1/chat/completions" \
  -H "Authorization: Bearer mf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6","messages":[{"role":"user","content":"你好"}]}'

Keep API keys out of client code

An API key grants access to your account's model usage. Store it in server-side environment variables. Do not embed keys in browser code, mobile app bundles or public repositories.

Create and revoke keys

Action	Endpoint	Behavior
List	GET /api/keys	Returns masked keys, creation times and last-used times
Create	POST /api/keys	Accepts { "name": "..." }; returns the plaintext key
Revoke	DELETE /api/keys/:id	Invalidates the key immediately

• Each account can have 10 active keys. Creating another returns 400 too_many_keys.
• Keys are stored as a hash and an encrypted copy. The list endpoint can recover plaintext for copying, but plaintext keys cannot be found by searching the database.
• Requests using a revoked key return 401.

Authentication errors

HTTP	error.type	Cause
401	unauthorized	Missing Authorization header, malformed key or revoked key
402	insufficient_credits	Insufficient balance; rejected before calling the provider
429	rate_limited	Gateway rate limit exceeded (60 requests per key per minute by default)

Use a session token with console APIs

The /api/auth, /api/account, /api/keys, /api/wallet and /api/mail APIs serve the console. They use the JWT returned by login:

curl -X POST "https://modelfold.ai/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your-password"}'

Tokens are valid for seven days by default. Changing or resetting a password invalidates sessions on other devices immediately while retaining the current device's session after a password change. You can sign out individual devices from the console's session list.

Security recommendations

• Create separate keys for development, staging and production so you can revoke them independently.
• Review each key's last-used time in the console and revoke keys you no longer use.
• The gateway records each call's model, endpoint, status, credits and latency. Review these in the console's usage history.