Player auth API
Endpoints
Create a new player account POST https://api.trytalo.com/v1/players/auth/register
Body keys Key Required Description email
⚠️ SometimesRequired when verification is enabled. This is also used for password resets: players without an email cannot reset their password identifier
✅ YesThe unique identifier of the player. This can be their username, an email or a numeric ID password
✅ YesThe password the player will login with verificationEnabled
❌ NoWhen enabled, the player will be sent a verification code to their email address before they can login
Sample request Show
Sample response Show Login to a player account POST https://api.trytalo.com/v1/players/auth/login
Body keys Key Required Description identifier
✅ YesThe unique identifier of the player. This can be their username, an email or a numeric ID password
✅ YesThe player's password
Sample request Show
Sample response (verification not enabled) Show
Sample response (verification enabled) Show Provide the verification code to start the player session POST https://api.trytalo.com/v1/players/auth/verify
Body keys Key Required Description aliasId
✅ YesThe ID of the alias to verify code
✅ YesThe 6-digit verification code sent to the player (must be a string)
Sample request Show
Sample response Show 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
✅ YesThe ID of the player's alias x-talo-player
✅ YesThe ID of the player x-talo-session
✅ YesThe 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
✅ YesThe ID of the player's alias x-talo-player
✅ YesThe ID of the player x-talo-session
✅ YesThe session token
Body keys Key Required Description currentPassword
✅ YesThe current password of the player newPassword
✅ YesThe new password for the player
Sample request Show 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
✅ YesThe ID of the player's alias x-talo-player
✅ YesThe ID of the player x-talo-session
✅ YesThe session token
Body keys Key Required Description currentPassword
✅ YesThe current password of the player newEmail
✅ YesThe new email address for the player
Sample request Show 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
✅ YesThe email address to send the verification code to. If no player with this email exists, the request will be ignored
Sample request Show 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
✅ YesThe 6-digit verification code sent to the email address (must be a string) password
✅ YesThe new password for the player
Sample request Show Toggle verification for a player account PATCH https://api.trytalo.com/v1/players/auth/toggle_verification
Headers Key Required Description x-talo-alias
✅ YesThe ID of the player's alias x-talo-player
✅ YesThe ID of the player x-talo-session
✅ YesThe session token
Body keys Key Required Description currentPassword
✅ YesThe current password of the player email
❌ NoRequired when attempting to enable verification if the player does not currently have an email address set verificationEnabled
✅ YesThe new verification status for the player account
Sample request (disabling verification) Show
Sample request (enabling verification, player does not have an email address) Show
Sample request (enabling verification, player has an email address) Show
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' }