Skip to content
maskostudioDocs

All pages

  • Overview/docs/use-cases
  • Mobile app/docs/use-cases#mobile
  • Website/docs/use-cases#website
  • Desktop/docs/use-cases#desktop
  • AI agents/docs/use-cases#agents
  • Videos/docs/use-cases#videos
  • Brand/docs/use-cases#brand
  • Start building/docs/ai-agents
  • Set up once/docs/ai-agents#set-up-once
  • Ask in plain words/docs/ai-agents#ask-in-plain-words
  • What your agent does/docs/ai-agents#what-your-agent-does
  • MCP server/docs/mcp
  • Masko for Cursor/docs/ai-tools/cursor
  • Masko in ChatGPT/docs/ai-tools/chatgpt
  • Start here/docs/tutorials#start-here
  • All tutorials/docs/tutorials
  • Create your first mascot/docs/tutorials/first-mascot
  • Create an animated character/docs/tutorials/first-animation
  • Make a character talk/docs/tutorials/make-it-talk
  • Put your mascot on your website/docs/tutorials/mascot-on-your-website
  • Guide onboarding with a talking mascot/docs/tutorials/web-onboarding-mascot
  • Add a mascot that celebrates progress and welcomes users back/docs/tutorials/web-progress-companion
  • Add a talking support mascot in the bottom right/docs/tutorials/web-support-mascot
  • Show a mascot while your AI thinks/docs/tutorials/ai-loading-mascot
  • Give your AI agent a face/docs/tutorials/ai-agent-face
  • Animate the mascot you already have/docs/tutorials/animate-your-mascot
  • How to make Telegram stickers/docs/tutorials/telegram-stickers
  • How to make Discord stickers/docs/tutorials/discord-stickers
  • Quickstart: your first animation/docs/quickstart
  • Terminal quickstart/docs/terminal
  • API keys and workspaces/docs/authentication
  • CLI browser login/docs/authentication/cli
  • How mascots work/docs/how-mascots-work
  • Credits and costs/docs/credits
  • From text/docs/create/from-text
  • From an image/docs/create/from-image
  • From a website/docs/create/from-website
  • From a brand book/docs/create/from-brand-book
  • Reference images/docs/manage/references
  • What you can generate/docs/generation
  • Pose-to-animation walkthrough/docs/generate/workflow
  • Images and poses/docs/generate/images
  • Animations/docs/generate/animations
  • Talking animations/docs/generate/talking
  • Logos, backgrounds and stickers/docs/generate/design-assets
  • Cursor follower/docs/generate/cursor-follower
  • Batch generation/docs/generate/batch
  • Image and video exports/docs/manage/media-exports
  • Canvases and releases/docs/canvas
  • Build a canvas/docs/canvas/build
  • Canvas templates/docs/canvas/templates
  • Generate canvas assets/docs/canvas/generate-all
  • Export a canvas/docs/canvas/export
  • Overview and demo/docs/player
  • Play one animation/docs/player/one-animation
  • Play a canvas/docs/player/canvas
  • Hosting and file formats/docs/generate/cdn
  • File sizes/docs/generate/file-sizes
  • Float a mascot on your Mac/docs/integrations/desktop
  • Jobs and polling/docs/manage/jobs
  • Webhooks/docs/manage/webhooks
  • Manage mascots and assets/docs/manage/collections
  • All endpoints/docs/reference
  • Requests and responses/docs/reference/conventions
  • Errors and recovery/docs/reference/errors
  • Command line reference/docs/terminal/commands
  • TypeScript SDK/docs/sdk/typescript
  • Changelog/docs/reference/changelog
  • Migrate to mascots and canvases/docs/manage/studio-migration
Get an API key
Documentation

CLI browser login

Sign the Masko CLI in through your browser instead of pasting an API key. Install it with the terminal quickstart; server integrations use API keys.

Sign in from the terminal

masko login                         # Open browser, approve, return automatically
masko login --no-browser            # Open the printed URL yourself on this computer
masko login --device --no-browser   # Device code for SSH or a remote terminal
masko login --scope read            # Request read-only access
masko whoami                        # Account, workspace, access, credits
masko logout                        # End this CLI session

Sign in on Masko, choose the workspace and click Connect; the CLI completes sign-in with PKCE (Control+C cancels). Without server support for browser sign-in, it shows an error and never falls back to API-key login.

  • Team authorization requires an owner or admin.
  • Access tokens last 15 minutes; refresh tokens rotate automatically and are stored in macOS Keychain.
  • Sessions last 90 days. See them, and sign one out, under Signed-in computers in Developers → API keys.

Choosing a workspace

Your choice (Personal workspace or a team) sets which projects, mascots, canvases, assets and jobs the session reaches and which balance pays. Run masko login again to switch; membership and project restrictions still apply.

IDs from another workspace return 404, as with API keys, while public mascot releases stay public. Unattached uploads, user templates, creator profiles and listings, and webhook registrations stay account-owned; source assets for mascot creation, references and template extraction must pass workspace checks.

An older CLI that gets 410 at login needs an update; API keys stay valid. MASKO_API_KEY overrides a saved session, and an invalid key fails rather than switching accounts. Save a key with masko login --api-key (asks for it) or --api-key-stdin.

masko logout removes the login on this Mac even when Masko cannot be reached; the session then stays valid until you sign it out under Signed-in computers.

Browser authorization (PKCE)

GET /v1/auth/config returns the authorization_endpoint and supported grants. The client masko-cli opens it with:

  • client_id=masko-cli, response_type=code, device_name, and scope=read|write.
  • redirect_uri=http://127.0.0.1:PORT/oauth/callback, using a temporary local port between 1024 and 65535. Other hosts, paths, query strings and fragments are rejected.
  • Independent random state and code_verifier values generated from 32 random bytes, base64url encoded. Send only state, code_challenge=BASE64URL(SHA256(code_verifier)), and code_challenge_method=S256 in the browser URL. Keep the verifier in memory.

After approval, check the exact callback path and state, then send client_id, grant_type: "authorization_code", code, the same redirect_uri and code_verifier as JSON to POST /v1/auth/token. Codes expire after 120 seconds and work once.

The callback never carries a token or API key. Cancelling returns error=access_denied with the original state; the CLI closes its listener on completion, cancellation or timeout (10 minutes at most).

Device-login REST contract

For masko login --device, when the browser runs on another computer:

  • POST /v1/auth/device: { "client_id": "masko-cli", "device_name": "My Mac", "scope": "write" }. Returns device_code, user_code, verification_uri, verification_uri_complete, expires_in (600 seconds), and interval (5 seconds) under data.
  • POST /v1/auth/token: send client_id, grant_type: "urn:ietf:params:oauth:grant-type:device_code", and device_code. Poll at the returned interval: keep waiting on authorization_pending, add 5 seconds to all later intervals on slow_down, and stop on access_denied, expired_token or invalid_grant.
  • On success, data contains access_token, refresh_token, token_type: "Bearer", expires_in, session_id, and session_expires_at. Never log these tokens.
  • Refresh at the same endpoint with client_id, grant_type: "refresh_token" and refresh_token, one refresh at a time, replacing the pair securely. Reusing a consumed refresh token revokes the session; if a refresh response is lost, log in again.
  • GET /v1/auth/session identifies the current key or session without secrets.
  • POST /v1/auth/revoke with { "refresh_token": "..." } ends only that session, immediately and idempotently.

These endpoints use Masko's JSON bodies and {data} / {error} envelopes, not a general third-party OAuth server or form-encoded token endpoint. All auth responses are no-store, and masko-cli is the only registered client.