Docs Login with Masky (SSO)

Masky API keys are generated at https://masky.ai/docs. No key? See "First: get an API key" in https://masky.ai/skill.md — an AI assistant can connect its user's account with one link, no developer page needed.

Login with Masky (SSO)#

Masky is also an OAuth 2.0 identity provider. Add a "Login with Masky" button to your own site: the user signs in and picks which of their avatars represents them on your site — the avatar's name + photo become the identity you receive, and (if they grant the generate scope) you can call this API to render avatars/turns on their credits, as that avatar.

1. Register your app (one-time). Use a first-party mky_ key from https://masky.ai/docs:

curl -s -X POST https://masky.ai/api/oauth/clients \
  -H "Authorization: Bearer $MASKY_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"My App","redirectDomains":["myapp.com"],"scopes":["profile","generate"]}'
# -> { "clientId": "mkc_…", "clientSecret": "mks_…", … }   # secret shown ONCE

Scopes: profile (identity via userinfo), avatars:read, generate (spend the user's credits on images/turns), tribes (tribe membership queries + credit-paid join), donations (propose user→user credit gifts; each needs the user's confirmation on masky.ai).

2. Send the user to consent. Open in their browser:

https://masky.ai/oauth-authorize.html?client_id=mkc_…&redirect_uri=https://myapp.com/callback&scope=profile%20generate&state=<csrf>

redirect_uri's host must be in your redirectDomains (https only, except localhost); a query string on it is fine — the code is appended with &. PKCE is supported for public clients: add code_challenge=<base64url(S256(verifier))>&code_challenge_method=S256 to the authorize URL and send code_verifier (no client_secret) in the token exchange.

3. Exchange the code for a token:

curl -s -X POST https://masky.ai/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"authorization_code","code":"<code>","redirect_uri":"https://myapp.com/callback","client_id":"mkc_…","client_secret":"mks_…"}'
# -> { "access_token":"mky_…", "token_type":"Bearer", "scope":"profile generate", "avatar":{ "id","name","picture" } }

The access_token is a scoped mky_ key — use it as the Authorization: Bearer on any endpoint above (subject to its scopes; rendering needs generate). Codes are single-use and expire in 5 minutes. Tokens do not expire and there is no refresh grant — store the token and reuse it; it stops working only when the user revokes it under Connected apps at masky.ai/docs. (Same for device-flow tokens: the expires_in in the device response is the 15-minute life of the pairing code, not of the token.)

4. Get the identity:

curl -s https://masky.ai/api/oauth/userinfo -H "Authorization: Bearer <access_token>"
# -> { "sub":"ava_…", "name":"Aphrodite", "picture":"https://…", "avatar_id":"…", "scope":"profile generate" }

sub is a stable pseudonym per (user, your app, avatar) — never the raw Masky uid, and un-correlatable across sites. Treat it as the user's account id on your side.

Users can review and revoke your app anytime from https://masky.ai/docs (Connected apps). MCP users get the same flow via the register_oauth_client + get_sso_integration_guide tools.

App / service identities (client_credentials)#

There are no standalone application accounts on Masky. Every identity — human or app — is an avatar on a user's account, and every identity you accept downstream must resolve through /oauth/userinfo. Never invent local identities in your own system (e.g. app_yourname) for a Masky-integrated app — that breaks the "every user is a verifiable Masky avatar" invariant for every site consuming Masky SSO.

When your app itself needs to act (a backend minting content, an agent running 24/7), give it a service avatar: create an avatar for the app on the owner's account, attach it to your client, and use client_credentials:

# Attach a service avatar to your client (owner's mky_ key; also accepted at registration time)
curl -s -X PATCH https://masky.ai/api/oauth/clients/mkc_… \
  -H "Authorization: Bearer $MASKY_API_KEY" -H "Content-Type: application/json" \
  -d '{"serviceAvatarId":"<one of your avatarIds>"}'

# Get a token that acts AS that avatar — no user, no consent; the secret is the credential
curl -s -X POST https://masky.ai/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"mkc_…","client_secret":"mks_…"}'
# -> { "access_token":"mky_…", "token_type":"Bearer", "scope":"…", "avatar":{ "id","name","picture" } }

The token behaves exactly like a user's SSO token: /oauth/userinfo returns a normal ava_ sub with the avatar's name and picture, generation bills the client owner's credits, and the owner can revoke it from Connected apps. Tokens are long-lived — request one and store it; don't mint a new token per call.

Tribes & credit gifts (SSO)#

With an SSO token you can integrate a creator's tribe (their community with a credit-priced join) and send credit gifts between users. {user} params accept a Masky uid or twitchUsername. None of these are public: membership queries only answer for the token holder's own tribe or own membership.

# Tribe info (`tribes` scope) — name, join cost, member count, whether the token's user is a member
curl -s https://masky.ai/api/tribes/<user> -H "Authorization: Bearer <access_token>"
# -> { "user":"…", "tribeName":"…", "joinCost":10, "memberCount":42, "isMember":false, "isOwner":false }

# Membership check — is <member> in <user>'s tribe? Caller must be one of the two.
curl -s "https://masky.ai/api/tribes/<user>/membership?member=<other>" -H "Authorization: Bearer <access_token>"
# -> { "tribeOwner":"…", "member":true, "joinedAt":1750000000000 }

# Join — charges joinCost from the user's credits (free for the creator's active Twitch subs)
curl -s -X POST https://masky.ai/api/tribes/<user>/join -H "Authorization: Bearer <access_token>"
# -> { "success":true, "isSubscriber":false, "charged":10 }

Credit gifts are two-phase (donations scope): your token can only propose — the transfer executes only after the user confirms on a masky.ai page with their own session, so a delegated token can never move credits by itself.

# 1) Propose a gift
curl -s -X POST https://masky.ai/api/donations/intents \
  -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" \
  -d '{"to":"<user>","amount":5,"note":"great stream!"}'
# -> { "intentId":"…", "status":"pending", "confirmUrl":"https://masky.ai/donate-confirm.html?intent=…", "expiresAt":… }

# 2) Open confirmUrl in a popup — the user clicks "Send credits" there.
#    The page postMessages {type:"masky:gift", status, intentId} to the opener (a hint);
#    poll for the authoritative status. Intents expire after 10 minutes.
curl -s https://masky.ai/api/donations/intents/<intentId> -H "Authorization: Bearer <access_token>"
# -> status: "pending" | "confirmed" | "cancelled" | "expired"

# 3) Gifts this user has sent to someone (totals + history)
curl -s "https://masky.ai/api/donations/sent?to=<user>" -H "Authorization: Bearer <access_token>"
# -> { "to":"…", "total":12.5, "count":3, "gifts":[{ "amount":5, "note":"…", "createdAt":… }] }

Gifted credits arrive as global Masky credits. The sender's transferable balance excludes credits locked to a creator's page or already spent, so confirm can fail with Insufficient transferable credits.

Full HTTP API (images, avatars, conversations, rendering — everything an SSO token with generate can call): https://masky.ai/masky-api.md · entry point: https://masky.ai/skill.md

Generate or manage your Masky API key any time at https://masky.ai/docs

Reading this as an AI assistant, or want to hand it to one? The same guide is plain markdown at masky.ai/masky-sso.md.