Webapp Authentication API Endpoints

Version: 1.1.0 Category: webapp Entity: Auth Base URL: ${webappBaseUrl} (default: http://localhost:8080) Last Updated: January 1, 2026

Endpoint Summary

Method Path Description Auth Required
POST /api/auth/signup Register a new player (signature) No (public)
POST /api/auth/login Authenticate via Cosmos signature No (public)
GET /api/auth/logout Clear the current session No (public prefix)

All /api/auth/* routes are public (no session enforced by PlayerAuthenticator). logout operates on the current session cookie if one is present.

Endpoint Details

POST /api/auth/signup

Register a new player with the operating guild. Asynchronous: persisting the pending player triggers a GuildMembershipJoinProxy chain message and the player ID is assigned later — login must be called separately once the ID exists.

Request body: primary_address, signature, pubkey, guild_id (required); username, pfp (optional). Signed message (buildGuildMembershipJoinProxyMessage): GUILD{guildId}ADDRESS{address}NONCE{nonce} (nonce 0).

Returns the standard envelope: 202 Accepted with { "success": true, "errors": {}, "data": null }, or 400/409 with keyed errors (signature_validation_failed, resource_already_exists).

POST /api/auth/login

Authenticate by Cosmos signature and receive a PHPSESSID session cookie. There is no username/password and no JWT/bearer token.

Request body:

Field Type Required Description
address string Yes Cosmos address logging in (e.g. structs1...)
signature string Yes Base64 signature over the login message
pubkey string Yes Base64 public key for address
guild_id string Yes Guild being logged into, type 0 (e.g. 0-1)
unix_timestamp string Yes Unix seconds; must be within 600s of server time

Signed message (SignatureValidationManager::buildLoginMessage):

LOGIN_GUILD{guildId}ADDRESS{address}DATETIME{unix_timestamp}

Success (200): { "success": true, "errors": {}, "data": null } plus Set-Cookie: PHPSESSID=....

Failure (401): { "success": false, "errors": { "signature_validation_failed": "Invalid signature" }, "data": null }. Other keys: player_address_does_not_exists, player_does_not_exists.

See examples/auth/webapp-login.md for full flows.

GET /api/auth/logout

Clear the current session. Returns the standard envelope { "success": true, "errors": {}, "data": null }.

Last Updated: January 1, 2026