Authentication

The ModelWorks API uses two ways to identify you, depending on what you're doing. Most developer workflows use API tokens (bearer tokens), while a smaller set of account-management actions require a web session cookie instead.

Base URL

All examples assume the following base URL:

https://modelworks.ai/api

Two ways to authenticate

Some endpoints are public (no auth needed) or optional (auth enriches the response but isn't required) — for example, viewing public circuits, public profiles, and health checks.

API tokens

API tokens are opaque random strings prefixed with mw_. They are not JWTs — there's no decodable payload, so don't try to inspect one to learn about the user. ModelWorks looks the token up server-side.

Getting a token

1. Log in to ModelWorks at modelworks.ai.
2. Open Settings → API Tokens.
3. Click Create to mint a new token. Creating a token requires your password and an active web session, so you have to do this from the website — you can't create a token via the API itself.
4. Copy the token immediately. It's shown only once at creation time; after you close the dialog, the full value is gone for good.

Tip: Treat your token like a password. Store it in a secret manager or environment variable, never in source control.

Using your token

Send it in the Authorization header using the Bearer scheme:

curl https://modelworks.ai/api/circuits \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Authorization: Bearer YOUR_API_TOKEN

Which endpoints accept an API token

API tokens work for the developer-facing parts of the API:

• Creating, reading, updating, and deprecating circuits
• Creating and managing circuit versions
• Running circuits (querying adaptors) and reading run results
• Boards and organizations
• Search

Endpoints that need a web session instead

A handful of endpoints touch sensitive personal data, so they can only be called while you're logged in to the website (the mw_session cookie must be present). They cannot be reached with an API token:

• Secrets
• Wallet
• API token management (listing, creating, or revoking tokens)
• Blobs
• Profile updates
• Password changes

Note: If you try to call one of these with a bearer token, you'll get a 401 Unauthorized response. Just open the website and perform these actions from the UI.

Public endpoints

You don't need any credentials to:

• View public circuits and their public versions
• View public user profiles
• Run a search
• Hit the health-check endpoints

For "optional auth" endpoints, sending a valid token may return extra fields (for example, whether you've starred a circuit), but the request succeeds without one.

Rate limiting

The /search endpoint is rate-limited to keep things fair for everyone. If you exceed the limit you'll receive a 429 Too Many Requests response — wait a moment and retry. When polling run results, prefer exponential backoff over tight loops (see Circuit Runs).

Keeping your token safe

• Keep it secret. It's shown only once at creation.
• Scope it. Create separate tokens per app or service so you can revoke one without affecting the others.
• Rotate it. Periodically revoke and recreate tokens to limit blast radius.
• Revoke on leak. If a token leaks, delete it immediately from Settings → API Tokens.