Skip to main content

Player auth API

Endpoints


Create a new player account

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

Body keys

KeyRequiredDescription
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

{ ... }

Sample response

{ ... }

Login to a player account

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

Body keys

KeyRequiredDescription
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

{ ... }

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

KeyRequiredDescription
aliasId YesThe ID of the alias to verify
code YesThe 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

KeyRequiredDescription
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

KeyRequiredDescription
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

KeyRequiredDescription
currentPassword YesThe current password of the player
newPassword YesThe 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

KeyRequiredDescription
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

KeyRequiredDescription
currentPassword YesThe current password of the player
newEmail YesThe 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

KeyRequiredDescription
email YesThe 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

KeyRequiredDescription
code YesThe 6-digit verification code sent to the email address (must be a string)
password YesThe new password for the player

Sample request

{ ... }

Toggle verification for a player account

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

Headers

KeyRequiredDescription
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

KeyRequiredDescription
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)

{ ... }

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

{ ... }

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

{ ... }

Delete a player account

DELETE https://api.trytalo.com/v1/players/auth/

Headers

KeyRequiredDescription
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

KeyRequiredDescription
currentPassword YesThe current password of the player

Sample request

{ ... }

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'
}