Player auth API

Endpoints

---

Create a new player account

POST https://api.trytalo.com/v1/players/auth/register

Body keys

Key	Required	Description
email	⚠️ Sometimes	Required when verification is enabled. This is also used for password resets: players without an email cannot reset their password
identifier	✅ Yes	The unique identifier of the player. This can be their username, an email or a numeric ID
password	✅ Yes	The password the player will login with
verificationEnabled	❌ No	When enabled, the player will be sent a verification code to their email address before they can login

Sample request

{ ... }

Sample response

{ ... }

---

Login to a player account

POST https://api.trytalo.com/v1/players/auth/login

Body keys

Key	Required	Description
identifier	✅ Yes	The unique identifier of the player. This can be their username, an email or a numeric ID
password	✅ Yes	The player's password

Sample request

{ ... }

Sample response (verification not enabled)

{ ... }

Sample response (verification enabled)

{ ... }

---

Provide the verification code to start the player session

POST https://api.trytalo.com/v1/players/auth/verify

Body keys

Key	Required	Description
aliasId	✅ Yes	The ID of the alias to verify
code	✅ Yes	The 6-digit verification code sent to the player (must be a string)

Sample request

{ ... }

Sample response

{ ... }

---

Logout of a player account (and invalidate the session token)

POST https://api.trytalo.com/v1/players/auth/logout

Headers

Key	Required	Description
x-talo-alias	✅ Yes	The ID of the player's alias
x-talo-player	✅ Yes	The ID of the player
x-talo-session	✅ Yes	The session token

---

Change the password of a player account

POST https://api.trytalo.com/v1/players/auth/change_password

Headers

Key	Required	Description
x-talo-alias	✅ Yes	The ID of the player's alias
x-talo-player	✅ Yes	The ID of the player
x-talo-session	✅ Yes	The session token

Body keys

Key	Required	Description
currentPassword	✅ Yes	The current password of the player
newPassword	✅ Yes	The new password for the player

Sample request

{ ... }

---

Change the email address of a player account

POST https://api.trytalo.com/v1/players/auth/change_email

Headers

Key	Required	Description
x-talo-alias	✅ Yes	The ID of the player's alias
x-talo-player	✅ Yes	The ID of the player
x-talo-session	✅ Yes	The session token

Body keys

Key	Required	Description
currentPassword	✅ Yes	The current password of the player
newEmail	✅ Yes	The new email address for the player

Sample request

{ ... }

---

Send a password reset email to an email address

POST https://api.trytalo.com/v1/players/auth/forgot_password

Body keys

Key	Required	Description
email	✅ Yes	The email address to send the verification code to. If no player with this email exists, the request will be ignored

Sample request

{ ... }

---

Reset the password of a player account (invalidates any existing session tokens)

POST https://api.trytalo.com/v1/players/auth/reset_password

Body keys

Key	Required	Description
code	✅ Yes	The 6-digit verification code sent to the email address (must be a string)
password	✅ Yes	The new password for the player

Sample request

{ ... }

---

Toggle verification for a player account

PATCH https://api.trytalo.com/v1/players/auth/toggle_verification

Headers

Key	Required	Description
x-talo-alias	✅ Yes	The ID of the player's alias
x-talo-player	✅ Yes	The ID of the player
x-talo-session	✅ Yes	The session token

Body keys

Key	Required	Description
currentPassword	✅ Yes	The current password of the player
email	❌ No	Required when attempting to enable verification if the player does not currently have an email address set
verificationEnabled	✅ Yes	The new verification status for the player account

Sample request (disabling verification)

{ ... }

Sample request (enabling verification, player does not have an email address)

{ ... }

Sample request (enabling verification, player has an email address)

{ ... }

---

Error codes

INVALID_CREDENTIALS

When authentication fails (i.e. wrong identifier or password), this error is returned. This error also occurs when trying to change a player password, trying to change an email address or toggling verification and the current password entered is incorrect.

{
  message: 'Incorrect identifier or password',
  errorCode: 'INVALID_CREDENTIALS'
}

{
  message: 'Current password is incorrect',
  errorCode: 'INVALID_CREDENTIALS'
}

VERIFICATION_ALIAS_NOT_FOUND

When trying to verify a player login, this error is thrown if the aliasId is not valid.

{
  message: 'Player alias not found',
  errorCode: 'VERIFICATION_ALIAS_NOT_FOUND'
}

VERIFICATION_CODE_INVALID

When trying to verify a player login, this error is thrown if the code is not valid.

{
  message: 'Invalid code',
  errorCode: 'VERIFICATION_CODE_INVALID'
}

IDENTIFIER_TAKEN

When trying to create a new player, this error is thrown if the identifier is already taken.

{
  message: 'Player with identifier boz already exists',
  errorCode: 'IDENTIFIER_TAKEN'
}

MISSING_SESSION

Players that use Talo Authentication must provide a session token in the request headers. This error is thrown when the session token is missing.

{
  message: 'The x-talo-session header is required for this player',
  errorCode: 'MISSING_SESSION'
}

INVALID_SESSION

Players that use Talo Authentication must provide a session token in the request headers. This error is thrown when the session token is invalid.

{
  message: 'The x-talo-session header is invalid',
  errorCode: 'INVALID_SESSION'
}

NEW_PASSWORD_MATCHES_CURRENT_PASSWORD

When trying to change a player's password, this error is thrown if the new password matches the current password.

{
  message: 'Please choose a different password',
  errorCode: 'NEW_PASSWORD_MATCHES_CURRENT_PASSWORD'
}

NEW_EMAIL_MATCHES_CURRENT_EMAIL

When trying to change a player's email address, this error is thrown if the new email matches the current email.

{
  message: 'Please choose a different email address',
  errorCode: 'NEW_EMAIL_MATCHES_CURRENT_EMAIL'
}

PASSWORD_RESET_CODE_INVALID

When trying to reset a player password, this error is thrown if the reset code is incorrect or has expired.

{
  message: 'This code is either invalid or has expired',
  errorCode: 'PASSWORD_RESET_CODE_INVALID'
}

VERIFICATION_EMAIL_REQUIRED

When attempting to toggle verification on, this error is thrown if the player does not have an email address set and one is not provided in the request.

{
  message: 'An email address is required to enable verification',
  errorCode: 'VERIFICATION_EMAIL_REQUIRED'
}