Tooling

API Tokens

API tokens authenticate the CLI, the SDK, and raw HTTP calls without a browser session — built for CI pipelines, coding agents, and scripts. Each token carries an explicit set of scopes, so a leaked build token can't touch what it wasn't granted. Create and revoke them at metaloot.app/settings/api-tokens.

Token Types#

mtl_api_…	Scoped API token — created in settings with the scopes and expiry you choose. The right choice for CI, agents, and anything unattended.
mtl_cli_…	CLI token — created by `metaloot login`'s browser approval, full access, revoked by `metaloot logout`. For interactive terminal use on your own machine.

The full token is shown once at creation and stored hashed — copy it immediately. If a token leaks, revoke it in settings; every token row shows its prefix, scopes, and last-used time to help you identify it.

Scopes#

assets:read	Browse public assets and read or download private assets you own.
assets:write	Edit metadata, publish or unpublish assets, and create animation variants.
assets:generate	Start paid generation jobs and inspect provider credit balances.
games:read	List your games, settings, OAuth linkage, and analytics.
games:write	Create games, update their settings, and upload game media.
deployments:write	Upload and publish game builds to Metaloot Hosting.
oauth:read	List OAuth applications and inspect their sign-in analytics.
oauth:write	Create and update OAuth applications and redirect URIs.

Presets

Assets read-only — assets:read. For games or scripts that only fetch assets.
Game builder — assets:read, games:read, games:write, deployments:write. The default, and the right preset for a coding agent building and deploying a game.
Full access — every scope, including paid generation and OAuth app management. Prefer narrower tokens.

Expiry options: 30 days, 90 days (default), 1 year, or never. A request with a missing scope fails with 403 "API token is missing the <scope> scope."— mint a new token rather than widening an old one you can't audit.

Using a Token#

CLI

# per-invocation (recommended for CI — nothing stored on disk):
METALOOT_TOKEN=mtl_api_… metaloot deploy

# or store it like a login:
metaloot login --token mtl_api_…

SDK

import { loadAsset } from "@metaloot/sdk/assets";

// Only needed for private assets; public assets need no token at all.
const buffer = await loadAsset("my-private-model", { token: process.env.METALOOT_TOKEN });

Raw HTTP

curl https://www.metaloot.app/api/cli/whoami \
  -H "Authorization: Bearer mtl_api_…"

Every platform API accepts Authorization: Bearer <token> — see the API Reference.

Security Practices#

Never commit tokens or ship them in a browser bundle — for a deployed game that needs a private asset, make the asset public or download the file into the build instead.
Give each consumer (CI job, agent, machine) its own token with a label, so revocation is surgical and the last-used column stays meaningful.
Prefer expiring tokens; "never" is for infrastructure you monitor.
Scope down: an agent that only builds and deploys doesn't need assets:generate (paid) or oauth:write.

Managing Tokens over HTTP#

The settings UI is backed by a small API (browser session required):

GET /api/tokens	List your tokens: id, label, kind, prefix, scopes, createdAt, lastUsedAt, expiresAt.
POST /api/tokens	Create a token: `{ label, scopes[], expiresInDays: 30\|90\|365\|null }`. Returns the plaintext token once.
DELETE /api/tokens/{id}	Revoke a token immediately.