Authentication

To call an operation, send its documentId and variables in JSON.

HTTP headers

Header	Required	Description
Content-Type	yes	application/json
Accept-Language	no	Preferred response language in standard HTTP format
Authorization	for protected operations	Bearer <sessionId>
X-Project-Context	yes	identity.contextToken from the current project configuration
X-Request-Id	no	Request identifier for tracing

Pass identity.contextToken from the project configuration unchanged. Authenticated operations also require a user session.

Password sign-in

Request

documentId: login

{
  "documentId": "login",
  "variables": {
    "login": "[email protected]",
    "password": "account-password",
    "rememberMe": true
  }
}

Response

200 OK

{
  "data": {
    "login": {
      "sessionId": "session-token",
      "sessionEnd": "2026-07-20 12:00:00",
      "twoFactorChallenge": null,
      "user": {
        "id": "1001",
        "email": "[email protected]"
      }
    }
  }
}

Send the returned sessionId in the Authorization header of subsequent protected requests.

Two-factor sign-in

When the user has a second factor enabled, login does not create a session. It returns a one-time challenge instead:

{
  "data": {
    "login": {
      "sessionId": null,
      "twoFactorChallenge": {
        "token": "opaque-challenge-token",
        "availableMethods": ["totp", "email", "recovery_code"],
        "expiresAt": "2026-07-19 12:10:00"
      }
    }
  }
}

Call requestTwoFactorChallengeCode first for email. The totp and recovery_code methods do not require that step.

Request

documentId: verifyTwoFactorChallenge

{
  "documentId": "verifyTwoFactorChallenge",
  "variables": {
    "challengeToken": "opaque-challenge-token",
    "method": "totp",
    "code": "123456"
  }
}

Response

200 OK

{
  "data": {
    "verifyTwoFactorChallenge": {
      "sessionId": "session-token",
      "sessionEnd": "2026-07-20 12:00:00",
      "user": {
        "id": "1001",
        "email": "[email protected]"
      }
    }
  }
}

Use the challenge from the current sign-in attempt. If it expires or reaches its attempt limit, start sign-in again. A successfully completed challenge cannot be reused.

Passkeys

Passkeys use a separate WebAuthn ceremony:

1. Get options through passkeyAuthOptions.
2. Pass the options to the browser WebAuthn API.
3. Send the assertion to loginPasskey.

A successful Passkey assertion creates a session without a password/2FA challenge.

Public operations

Operations that start or finish authentication and public project data do not require Authorization:

Operation	Purpose
registerEmail	Start email registration
confirmRegistrationCode	Verify the six-digit registration code
login, loginGameAccount	Password sign-in
sendMagicLink, loginMagicLink	One-time link sign-in
sendMagicCode, loginMagicCode	One-time code sign-in
requestTwoFactorChallengeCode	Send the email code for an existing challenge
verifyTwoFactorChallenge	Finish two-factor sign-in
passkeyAuthOptions, loginPasskey	Passkey sign-in
sendPasswordRecoveryEmail, confirmPasswordRecoveryCode	Password recovery
projectSettings, servers	Public project configuration

Social authentication is configured and published by each project. It does not replace local account security rules.

Protected request example

cURL

curl -X POST https://api.mmo-web.dev/graphql \
  -H "Accept-Language: en" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer session-token" \
  -H "X-Project-Context: project-context-token" \
  -d '{"documentId":"me","variables":{}}'