Skip to main content

​
API key authentication

Send the API key in every request:
API keys are server-side secrets. Never expose them in browser JavaScript, mobile bundles, public repositories, logs, analytics, or prompts. Rotate a key if it may have leaked. GET /v1/me identifies the API key and the Mint account that owns it. Assets created with the key belong to that account and can be read through supported API, MCP, and Mint surfaces.

​
Downstream users and workspaces

One API key identifies one Mint account, not the individual users of your application. Keep the key on your server, authenticate your own users there, and store the returned Mint operation and asset IDs against your own user, team, collection, or workspace records. Do not give one shared API key directly to multiple client applications and expect Mint to separate their resources.

​
OAuth for approved integrations

Mint-approved installed integrations can send a short-lived OAuth access token in the same Bearer header. They use Authorization Code with S256 PKCE, the resource https://api.mint.gg, and one or both asset permissions:
  • mint:assets:read reads account-owned assets and durable files.
  • mint:assets:generate estimates, creates, reviews, retries, optimizes, and polls asset work.
The integration receives its public client ID and exact callback URLs from Mint. It does not use a client secret or dynamically register these permissions. Refresh tokens remain in the integration’s server-side HttpOnly session and rotate on use. OAuth access acts on the signed-in Mint account’s default developer project without creating a hidden API key. GET /v1/me returns authentication.type: "oauth", the client ID, granted scopes, and the owning account. Permanent asset deletion remains API-key-only.

​
Rate limits

Mint uses continuously refilling account-level limits. API keys and approved OAuth integrations owned by the same Mint account share these limits. The general request limit and a paid-work limit apply together when both are relevant. Successful responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset for the active bucket. X-RateLimit-Reset is the Unix timestamp when the continuously refilling bucket should be full again. A 429 Too Many Requests response includes the same rate-limit headers plus Retry-After; wait at least that long before retrying. Use bounded polling rather than a tight loop. These limits protect the service without restricting ordinary integrations. Contact Mint before intentionally scheduling sustained traffic near a limit.

​
Retry policy

Retry connection failures, 429, and retryable 5xx responses with exponential backoff and jitter. Respect Retry-After when present. Do not blindly retry validation, authentication, payment, or conflict responses. A 400 validation problem can report up to five invalid fields in errors. Each entry includes a field path, validation code, and readable message. Correct every listed field before sending the request again.
Every API response includes X-Request-Id. Save it with failed-request logs and include it when contacting Mint support. Problem type URLs are stable public error categories; branch on the complete URL rather than matching prose in detail. For ordinary mutations, Mint creates an internal request key automatically. You do not need to send another header.

​
Optional retry protection

If your application will retry a mutation when it cannot tell whether Mint accepted the original request, send an optional Idempotency-Key. Generate one stable key before the first attempt and reuse it only for retries of that same request.
The same idempotency key, authenticated principal, and request return the existing operation. The same principal and key with different input return a conflict. Different API keys and OAuth authorizations do not collide with one another. Retrying without a caller-supplied key can start another operation when the first response was lost. Some actions also protect the asset’s current state. Approving Asset Pack items that already started returns their current work without another charge. Repeating the same optimization level does not create another optimized copy. Smart topology and animation create additional outputs, so retry an uncertain request only with the stable key supplied on its first attempt.