Skip to content
Masko logomasko
Docs
QuickstartAPI reference
Documentation

API keys and workspaces

Send a bearer credential with protected REST requests. For a backend or script, create an API key. The Masko CLI also supports browser login.

Creating API Keys

Create a key in API keys for the workspace you want to use. Choose write access to generate or edit assets; read access only permits GET requests.

API keys use the format masko_{64-hex-characters}. The raw key is shown once; Masko stores its SHA-256 hash. Save it as MASKO_API_KEY in your server environment or secret manager.

API Keys

Check the connection with a free balance request:

curl https://api.masko.ai/v1/credits \
  -H "Authorization: Bearer $MASKO_API_KEY"

Keep the key on your server. Never include it in browser JavaScript, a distributed application, or a public repository.

Personal vs Organization Keys

The credential selects the workspace for each request:

  • Personal keys access personal projects and spend personal credits.
  • Organization keys access team projects and spend the team's credit pool. Team owners and admins can create these keys; project access restrictions still apply.

Switch workspaces in the dashboard before creating the key. A resource in another workspace returns 404, even when your account belongs to both workspaces. Use the credential issued for the target workspace.

Unattached uploads, user templates and webhook registrations retain account-level ownership. Source assets attached to a mascot must pass that mascot's workspace access checks.

Browser login for Masko CLI

Run masko login to approve access in your browser. Follow CLI browser login for workspace selection, device login, sessions and the authorization endpoint contract.

Distributed application credentials

For customer playback, your backend uses a restricted application secret to issue temporary mascot URLs. Your shipped app receives the URL rather than an authoring key. See customer playback access.

Rate Limits

A limited request returns 429. Follow errors and recovery for backoff and safe retries.

Credits

Check GET /v1/credits before paid generation. See credits and costs for model rates, source-image charges and refunds.

Error Codes

Missing or invalid credentials return 401; insufficient permissions return 403; inaccessible resources return 404. See the error reference for response fields and recovery.

Continue with the REST quickstart to create your first mascot.