User directory and provisioning

Use these /v1 user routes to create a member, resolve an identifier, search, update profile fields, and change account status. Community-scoped list/get sit in the Community folder; they are the same members, not a second user model.

WARNING

Keep community API keys server-side. Public examples use member@example.com and <COMMUNITY_API_KEY> only.

Which call should I use?

You have	Call
Nothing yet	Create New User
Email or numeric platform id	Get User Data `POST /v1/users/info`
Community ObjectId + member ObjectId or email	Get user
Need a directory page	Get Users with Filters with both `fields` and `filter`
Need the default community first page	Get community users with no query string
Custom fields, XP, coins	Update user / user-field writes, not community GET
Soft-delete or restore	Manage User Account

GET /v1/users/{userId} is not mounted. Use POST /v1/users/info instead.

Identifiers

Email works on info, community get, filter, manage, mini-games, and streak logs (unknown email on streaks is 404).

Numeric platform userId works on POST /v1/users/info. It 404s on community GET userId.

Mongo _id works on community GET. It 404s on idOrEmail in info.

Username is not a lookup key on those reads.

Filter vs community list

Filter requires both fields and filter. Empty "filter": {} is a valid directory read. Unknown email is 200 with zero rows, not 404.

Community list without query returns the default page. page / limit query flags currently return empty data.

Soft-deleted members can still appear in filter and in community GET-by-email. Manage status is not proof that search is empty.

Manage status

Validation text mentions remove and restore. action: "delete" still performs a soft-delete (USER_SOFT_DELETED). restore returns USER_RESTORED. Test delete and restore on a disposable user.

Milestones

POST /v1/users/milestones/ is mounted. milestones must be a string. Unknown ids return 400 Milestone not found: ….

Auth errors you will see

Code	Meaning
`401 AUTHENTICATION_REQUIRED`	Missing Bearer token on hardened user routes
`401 Token is wrong.`	Invalid token
`403`	Valid key, missing permission (for example `getUserData`)