Connect your agent to Miximodel

The Platform API gives advanced users and AI agents programmatic, token-scoped access to their own Miximodel account — the same data the app shows them, over a stable REST surface and a hosted MCP server.

There are zero admin capabilities anywhere in this surface — no moderation, no user management, no global configuration. A token can only ever act on its own owner's account, scoped to the abilities it carries.

Every request carries a Bearer token in the Authorization header:

Authorization: Bearer miximodel_cli_xxxxxxxxxxxx…

There are two token families, row-isolated by type — a token of one family can never authenticate the other surface:

Personal access tokens (PATs)

Visit /settings/personal-access-tokens while signed in:

1. Open the Create token dialog. Read scopes are pre-checked, except the two sensitive reads (chat:read, vault:read); write scopes and studio:generate are unchecked (explicit opt-in).
2. Confirm with your password and generate the token → the one-time miximodel_cli_… plaintext is shown once. Copy it now; it is never recoverable. Minting any long-lived credential (a PAT, a CLI device approval, an MCP connection) asks for your password, like deleting the account; an account created with Google or X sets one first through "Forgot password".
3. The token appears in your list with its scope badges; revoke it any time.

When your password is reset

A password reset assumes the old password was compromised. It revokes every personal access token — including the one miximodel login minted — and every MCP connection, and signs out every session. Afterwards, mint new tokens, run miximodel login again, and reconnect your MCP client: its tokens are refused from then on, so it has to go through consent again.

A token carries a subset of the ability catalogue. Each /api/v1 route and each MCP tool requires exactly one ability; a token lacking it gets a non-enumerating 403 (REST) / tool_error (MCP). Only what does not mutate is ever pre-selected for you: write abilities and studio:generate must be explicitly granted (studio:generate is never implicit — it spends credits), and so must the two sensitive reads, chat:read and vault:read.

The catalogue contains no * wildcard and no admin/moderation verb — by construction (a forbidden ability is rejected at mint, at the validator, and at the middleware). A unit test holds this table to the catalogue in code.

• IDs are UUIDs. The wire never exposes a numeric database id. Resources are addressed and referenced by uuid.
• Pagination is opaque-cursor. List endpoints accept ?limit= (1–50, default 20) and ?cursor= (an opaque token from the previous page's nextCursor). Walk until nextCursor is null. No page/offset, no total count.
• Media URLs are short-lived signed URLs. Treat them as ephemeral; re-fetch the resource to refresh.
• Rate limits are per-token, quotas are per-user. Two tokens of the same user get independent per-minute burst budgets; day-scale quotas (e.g. posts 100/day) are keyed on the ACCOUNT, so rotating an access token does not reset them. Write paths and studio:generate carry tighter sub-limits. A 429 carries a Retry-After header.

Every error is a application/problem+json document:

{
  "type": "https://miximodel.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "This token does not carry the required ability."
}

Branch on type (the /problems/<kind> suffix), not on the status alone — some statuses carry several kinds:

Error bodies never leak a database field, a stack trace, an internal id, or a secret.

claude mcp add --transport http miximodel https://miximodel.com/mcp

--transport http is required: without it Claude Code registers a local stdio command, not a remote server. Any other MCP client takes the same URL as a Streamable-HTTP server and discovers the rest on its own.

On first use the client runs the OAuth 2.1 handshake (below) and opens a browser consent page where you — signed into Miximodel — review the requesting app and its requested scopes, then Approve (with your password) or Deny. On approve, the client receives a miximodel_mcp_… token and the tools become available.

The server is a standards OAuth 2.1 Authorization Server; a compliant MCP client runs the whole flow for you:

1. Discovery — GET /.well-known/oauth-authorization-server (+ …/oauth-protected-resource).
2. Dynamic client registration (RFC 7591) — POST /mcp/oauth/register mints a public client_id (no secret; token_endpoint_auth_method: none).
3. Authorize + consent — the browser opens /mcp/oauth/authorize; you approve the scopes. PKCE S256 is required (the plain method and a missing challenge are rejected).
4. Token — POST /mcp/oauth/token exchanges the one-time authorization code (+ PKCE verifier) for a short-lived access token (1h) and a rotating refresh token (30d). Refresh-token reuse revokes the whole grant family.
5. Revoke — POST /mcp/oauth/revoke (RFC 7009) tears a connection down.

Security posture: redirect URIs are exact-matched, authorization codes are single-use (atomic claim), consent is bound to your session, and no code/token/secret is ever logged.

MCP tokens use the same ability catalogue as the REST API. Request only what your workflow needs; a tool whose ability the token lacks returns a non-enumerating tool_error.

Each tool is a thin wrapper over the same service its /api/v1 sibling uses, returns the same UUID/signed-URL shape, and is gated on its ability. MCP annotations (readOnlyHint / destructiveHint / idempotentHint) let your client prompt for confirmation on destructive or costly tools.

Read

Write / action

• Costly/destructive tools (generate_studio, manage_applicant, manage_booking) are annotated so your client asks you to confirm. Cost and consent guardrails are enforced server-side — the MCP layer never re-implements them; it surfaces a generic tool_error on refusal.
• Uploads can't stream binaries over MCP: upload_portfolio returns a signed PUT URL your host uploads to, then confirm_portfolio persists it.
• Revoke a connection with POST /mcp/oauth/revoke (RFC 7009). Resetting your Miximodel password revokes every MCP connection at once.

See authentication for the token model and the REST endpoints for the surface these tools mirror.

Two scopes, on purpose. The signup picker and the post-signup declaration prompt are different lists on the web too: signup refuses Agency (it needs extra mandatory fields) and Client (an unused persona), while the declaration prompt is fed the whole catalogue. ?scope= is how a client asks for the one it needs; an unknown scope is a 422 validationFailed, never a silent fallback. Declaring agency requires agencyName, registrationNumber and phone in the same PATCH /api/v1/me/role body (website optional).

Why only one of them needs a token. Exposure follows each scope's web twin: the signup list is served to anonymous visitors on the public /signup page, while the declaration list only ever reaches an authenticated (and role-pending) browser through the availableRoles Inertia prop. Any token is enough — the gate is authentication, not a scope, so a read-only token still renders the screen.

Roles are identified on the wire by their stable slug (makeup-artist), never a numeric id — the same identifier campaign links use. Echo that slug back on POST /api/v1/auth/register (role) and PATCH /api/v1/me/role (role). A slug outside the scope you are calling is a 422 invalidRole.

Two post counts, on purpose

The API exposes two different post totals. They answer different questions and are expected to disagree — the names say which is which:

The invariant is postsCount <= totalPostCount for the same user, and the difference is made entirely of rows that viewer cannot see. postsCount (plus followersCount / followingCount) is served from a 2-minute cache and is busted on follow / unfollow and on post create / delete, so it is normally exact; isFollowing is never cached.

curl -s "https://miximodel.com/api/v1/me/portfolio?limit=20" \
  -H "Authorization: Bearer $MIXIMODEL_TOKEN" -H "Accept: application/json"
# → { "data": [ … ], "nextCursor": "eyJ…" }   (walk until nextCursor === null)

The CLI signs in with the OAuth 2.0 device authorization grant (RFC 8628):

miximodel login        # prints a one-time code and opens the approval page
miximodel whoami       # GET /api/v1/me

miximodel login prints a code and opens https://miximodel.com/device in your browser. Sign in to Miximodel, check that the code matches, and approve with your password. The CLI then stores a miximodel_cli_… token — a personal access token like any other, listed and revocable under Settings → Personal access tokens.

• Scopes. By default the CLI asks for read abilities only, and neither of the sensitive reads (chat:read, vault:read). Pass --scope "whoami:read notices:write …" to request others, studio:generate included.
• Where the token lives. $XDG_CONFIG_HOME/miximodel/credentials.json (~/.config/miximodel/credentials.json by default).
• Another host. Set MIXIMODEL_API_URL to point the CLI at a non-production server.
• After a password reset the token is revoked: run miximodel login again.

Run miximodel --help for the full reference. Every command calls one /api/v1 route and needs the ability that route lists in the endpoint reference.