MagicWeave SDK: Player Authentication (apps/client/client_auth)

This guide documents the current behavior of the client auth module used by game clients (Unity, Unreal, web, mobile).

The module supports:

• Email + password signup/login
• Passwordless OTP login
• Google Sign-In token exchange
• Apple Sign-In token exchange
• MagicWeave access + refresh token issuance

Base URL and Route Prefix

Use one of these deployment styles:

• Split client API deployment: http://localhost:8001
• Combined deployment: http://localhost:8000/client

In both styles, auth routes are under /auth.

Examples:

• POST http://localhost:8001/auth/signup
• POST http://localhost:8000/client/auth/signup

Required Headers

All client auth calls require:

• x-client-id: <project_client_id>
• x-client-secret: <project_client_secret>
• Content-Type: application/json

If either client credential header is missing or invalid, the API returns 401.

Response Shape

Auth responses use:

{
  "success": true,
  "access_token": "jwt-or-null",
  "refresh_token": "jwt-or-null",
  "message": "human-readable status"
}

During OTP-required steps, tokens are null until OTP verification succeeds.

Endpoints

• POST /auth/signup
• POST /auth/login
• POST /auth/verify-otp
• POST /auth/google-signin
• POST /auth/apple-signin

OAuth Configuration Prerequisite

Before using social login endpoints, configure OAuth credentials via admin OAuth broker routes:

• GET /oauth-broker/{org_id}/{project_id}
• PUT /oauth-broker/{org_id}/{project_id}/google
• PUT /oauth-broker/{org_id}/{project_id}/apple
• DELETE /oauth-broker/{org_id}/{project_id}/{provider}

Google can include one or more of:

• google_web_client_id
• google_android_client_id
• google_ios_client_id

Apple currently requires:

• apple_client_id

Common Auth Flow Patterns

Pattern A: Email + Password

1. POST /auth/signup with email + password
2. If verification required, enter OTP and call POST /auth/verify-otp
3. Use returned access token for protected SDK endpoints

Pattern B: Passwordless OTP

1. POST /auth/login with password: null
2. Player enters OTP from email
3. POST /auth/verify-otp
4. Use returned tokens

Pattern C: Google/Apple

1. Complete provider sign-in in client SDK
2. Send provider token to MagicWeave endpoint
3. Receive MagicWeave tokens
4. Use tokens for downstream SDK calls

Error Handling Reference

Common status codes in this module:

• 200: auth action succeeded
• 400: invalid OTP, missing OAuth config, missing token email claim, or invalid social config
• 401: invalid client credentials, invalid password, or invalid OAuth token/issuer
• 5xx: unexpected server or upstream verification issue

Recommended client behavior:

• Retry only transient 5xx failures.
• Prompt retry/correction for 400/401.
• For login failures on unknown users, route to signup flow.

cURL Quick Start

Use the endpoint pages for complete examples:

• Signup (email + password)
• Passwordless login (via /auth/login)
• Verify OTP
• Google Sign-In
• Apple Sign-In

Integration Checklist

• Keep x-client-id and x-client-secret secure (prefer your trusted backend where possible).
• Choose your UX path: password login, OTP login, Google, Apple, or mixed.
• Configure OAuth provider credentials before enabling social sign-in.
• Persist and refresh tokens in your session/auth layer.
• Track analytics for login start, OTP sent, OTP verified, success, and failure.

Notes

• OTP flow is email-based.
• OTP validity and verification logic are server-controlled.
• Access and refresh tokens are JWTs issued by MagicWeave.