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

Once you are a verified developer, 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) · verified developers
GET /dev/apps	List your apps
POST /dev/apps/update	Edit (scope change → re-review) · verified developers
POST /dev/apps/secret	Regenerate the secret · verified developers
POST /dev/apps/delete	Delete + revoke tokens
POST /developers/apply	Apply to the developer program
GET /developers/mine	Your developer status and applications
POST /developers/withdraw	Withdraw a waiting application

Without verification, the three marked calls answer DEVELOPER_REQUIRED. Listing and deleting your own apps always work, and nothing your app's users do is ever gated. If staff revoke your developer access, your apps are suspended (not deleted) and you are told why.

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.