Let people sign in with MewGem and access their data with consent. This is the standard OAuth 2.0 Authorization Code flow — any OAuth2 client library works.

API base: https://api.mewgem.me (dev http://localhost:4080) · Consent screen: https://mewgem.me/authorize

1. Register an app

On the Developer page, create an app with a name, one or more redirect URIs (https, exact-matched), and the scopes you need. You receive a client ID (app_…) and a client secret (mgk_…).

⚠️ The client secret is shown once. Keep it server-side — never in browser or mobile code. New apps are staff-reviewed before the flow works.

2. Scopes

Scope	Grants	Tier
identity	Username and avatar
profile:read	Public profile (bio, banner)
email	Email address
spaces:read	Spaces the user belongs to
events:read	Events and RSVPs
act	Act on the user's behalf	Tier 2
content:write	Post/modify content as the user	Tier 2
billing:read	View billing & membership	Tier 2

Privileged scopes are only available to Tier 2 (partner) apps, promoted by MewGem staff. Request the least you need — userinfo returns only fields your granted scopes cover.

3. Send the user to consent

https://mewgem.me/authorize
  ?client_id=app_xxx
  &redirect_uri=https://yourapp.com/oauth/callback
  &scope=identity%20email
  &state=<random-anti-csrf>

On approve, the user is redirected back to your redirect_uri with ?code=code_xxx&state=…. Verify state matches what you sent. On cancel you get ?error=access_denied.

4. Exchange the code (server-side)

POST https://api.mewgem.me/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "code_xxx",
  "client_id": "app_xxx",
  "client_secret": "mgk_xxx",
  "redirect_uri": "https://yourapp.com/oauth/callback"
}

Returns access_token (Bearer, valid 30 days, revocable). The code is single-use and expires in 5 minutes; the redirect_uri must match step 3.

5. Call the API as the user

GET https://api.mewgem.me/oauth/userinfo
Authorization: Bearer at_xxx

→ { "sub": "alice", "username": "alice", "picture": "…", "email": "…" }

sub is always present; other fields appear only for granted scopes. Revoke a token with POST /oauth/revoke { token }. Users can disconnect your app from Settings → Connected Apps.

Endpoint reference

Method & path	Purpose
GET /oauth/authorize	Consent-screen data
POST /oauth/consent	User approves → one-time code
POST /oauth/token	Exchange code → access token
GET /oauth/userinfo	The user's data (scope-filtered)
POST /oauth/revoke	Revoke a token
POST /dev/apps	Create an app (secret shown once)
GET /dev/apps	List your apps
POST /dev/apps/update	Edit (scope change → re-review)
POST /dev/apps/secret	Regenerate the secret
POST /dev/apps/delete	Delete + revoke tokens

Security

• Keep the client secret server-side.
• Always send and verify state (CSRF protection).
• Register exact redirect URIs — MewGem matches origin + path exactly.
• Access tokens are bearer credentials: hashed at rest, revocable, 30-day expiry.

---

Building a MewGem-operated service (not a third-party app)? First-party services use the cross-service auth broker for single sign-on from mewgem.me instead of OAuth. See docs/SERVICE-AUTH-BROKER.md in the repository.