Skip to main content

MagicWeave SDK: Player Profile (apps/client/client_profile)

This guide is for game developers integrating player profile APIs from the MagicWeave SDK.

The client_profile module lets you:

  • create a player profile
  • fetch the logged-in player profile
  • update player profile fields
  • delete the player profile

It is designed to back the shared profile layer (nickname, avatar, profile background, country) that your game can use across UX surfaces.

Base URL and Route Prefix​

Use one of these deployment styles:

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

Profile routes are under:

  • /profile

Examples:

  • POST http://localhost:8001/profile/ (split)
  • POST http://localhost:8000/client/profile/ (combined)

Required Authentication and Headers​

All profile endpoints require:

  • x-client-id: <your_project_client_id>
  • x-client-secret: <your_project_client_secret>
  • Authorization: Bearer <magicweave_access_token>
  • Content-Type: application/json

Important:

  • The bearer token must be a valid MagicWeave access token.
  • The authenticated user must have client.profile permission.

Profile Data Model​

A profile contains:

  • nickname (required on create)
  • avatar_url (optional)
  • profile_bg (optional)
  • country (optional)

Response shape:

{
  "id": 1,
  "user_id": 100,
  "nickname": "PlayerOne",
  "avatar_url": "https://cdn.example.com/avatar.png",
  "profile_bg": "https://cdn.example.com/background.jpg",
  "country": "IN",
  "created_at": "2026-04-15T10:00:00Z",
  "updated_at": "2026-04-15T10:00:00Z"
}

Endpoints​

1) Create Profile​

POST /profile/

Request body:

{
  "nickname": "PlayerOne",
  "avatar_url": "https://cdn.example.com/avatar.png",
  "profile_bg": "https://cdn.example.com/background.jpg",
  "country": "IN"
}

Behavior:

  • Creates exactly one profile for the authenticated user.
  • If a profile already exists, returns 409.
  • On first successful profile creation, backend also ensures a wallet exists for the user.

Reference: Create profile

2) Get Profile​

GET /profile/

Behavior:

  • Returns the profile for the authenticated user.
  • Returns 404 if no profile exists yet.

Reference: Get profile

3) Update Profile​

PATCH /profile/

Request body (partial update; only send fields you want to change):

{
  "nickname": "PlayerOneRenamed",
  "avatar_url": "https://cdn.example.com/new-avatar.png"
}

Behavior:

  • Updates only provided fields.
  • Returns 404 if profile does not exist.

Reference: Update profile

4) Delete Profile​

DELETE /profile/

Response:

{
  "success": true
}

Behavior:

  • Deletes the user profile.
  • Returns 404 if profile does not exist.

Reference: Delete profile

Common Error Codes​

  • 401: missing/invalid project headers, missing/invalid/expired bearer token
  • 403: authenticated user lacks client.profile permission
  • 404: profile not found
  • 409: profile already exists for this user

cURL Examples​

Create​

curl -X POST "http://localhost:8001/profile/" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"nickname":"PlayerOne","avatar_url":"https://cdn.example.com/avatar.png","profile_bg":"https://cdn.example.com/background.jpg","country":"IN"}'

Get​

curl -X GET "http://localhost:8001/profile/" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>"

Update​

curl -X PATCH "http://localhost:8001/profile/" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"nickname":"ProPlayer","country":"US"}'

Delete​

curl -X DELETE "http://localhost:8001/profile/" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>"

Integration Notes for Game Teams​

  • Complete login/signup first using client_auth to obtain access tokens.
  • Create profile once after first login (or first-time onboarding screen).
  • Use PATCH /profile/ for lightweight settings/profile edit screens.
  • Keep avatar/background URLs as CDN links controlled by your game pipeline.
  • Handle 409 gracefully by switching from create flow to update/fetch flow.