Player auth API

Talo provides a powerful and secure authentication system out of the box. You can use Talo to authenticate players using their email, username, or any other identifier you choose.

Learn more about player authentication here.

Identifying players using Talo Authentication

Once you have registered a player, you can identify them using the identify endpoint. You will need to ensure that:

1. The identifier is the one you used to register the player (email, username, etc.)
2. The service is set to talo
3. The x-talo-session header contains the session token you received from the login/register endpoint

To create a new session token, you will need to go through the login flow again for the player.

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)

{ ... }

---

Delete a player account

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

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

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