Requests pertaining to user accounts should be made to the /accounts/ path.
No auth required.
The client can either request to be logged in as a guest user, or as a registered user. If they login as a guest, then when the token expires, all games they were in are abandoned. If logging in as a registered user, both email and password are required.
The token must be retained by the client, and resent in the header of all future requests.
Request:
POST /accounts/login
POST parameters:
credentialType, one of "password" or "guest"email (optional)password (optional)Response:
200 OK with a response body like:
{
"creationTime" : 1474703168520,
"user" : {
"userId" : 1,
"username" : "ezekial"
},
"token" : "c+/52wss+12ghKsS"
}
Possible errors:
login.bad_credentials if the email/password combo is invalidlogin.bad_credential_type if credential-type doesn't have a valid valuelogin.account_unverified if the account is not yet verifiedRequest:
POST /accounts/logout
Response:
204 No Content
No auth required.
When creating an account, the user needs to supply an email address (unique), a password and a username (need not be unique). The email address will need to be validated, but the user is given a grace period of some time in which they may still login and play games with an unvalidated account.
The username is simply a display name and cannot be used to identify a user.
Request:
POST /accounts/register
Request body:
{
"email": ...,
"password": ...,
"username": ...
}
Response:
200 OK with a response body like:
{
"user" : {
"userId" : 1,
"username" : "ezekial"
}
}
Additionally, the Location header will be set to the location of the newly created user resource: /accounts/user/{user-id}.
An email will be sent to the provided email address with a link to confirm the account. (Todo: resend confirmation, change email address, expire confirmation link, expire accounts if unconfirmed for a long time).
Possible errors:
register.email_already_existsregister.email_not_validregister.password_not_validregister.username_not_validThis request is used to get a list of all the rooms and sessions that a player belongs to.
Request:
GET /accounts/{user-id}/rooms-and-sessions
Response:
200 OK with a response body of the form:
{
"rooms": [ ... ],
"sessions": [ ... ]
}
If the user is not a member of any rooms or sessions, empty lists will be returned.
The exact format of the room and session objects can be found on the respective documentation pages under the appropriate GET request.
Request:
GET /accounts/{user-id}
Response:
200 OK with a response body like:
{
"permissions": 0,
"guest": false,
"userId": 6,
"email": "testing2@example.com",
"username": "second_user"
}
You can only fetch user info for the account you are logged in as.
Request:
POST /accounts/{user-id}
Request body:
{
"email": ...,
"password": ...,
"username": ...
}
Any of the fields can be missing to leave the value unchanged, unlike in the register request.
Response:
204 OK
Note that changing an account's email will mean that the account will require reverification.
Errors are as in registration.
Sending this request causes an account recovery code to be sent to the given email, if there is a verified account with the given email registered with Kangaroo.
Request:
POST /accounts/reset
Request body:
{
"email": "user@example.com"
}
Response:
204 No Content
The response will be a success even if the user doesn't exist so as to avoid revealing valid email addresses.
Reset an account's password using the code generated with the "Request account recovery" request.
Request:
POST /accounts/reset
Request body:
{
"code": "...",
"password": "..."
}
Response:
204 No Content
After creating an account, an email containing a code will be sent to the account's email address. You will need to send this code to Kangaroo in order to verify the account before you are able to login.
Request:
POST /accounts/verify
Request body:
{
"code": "..."
}
Response:
204 No Content