Skip to main content

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

Sample request

{ ... }

Sample response

{ ... }

Login to a player account

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

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

Sample request

{ ... }

Sample response

{ ... }

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

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

Change the password of a player account

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

Sample request

{ ... }

Change the email address of a player account

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

Sample request

{ ... }

Send a password reset email to an email address

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

Sample request

{ ... }

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

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

Sample request

{ ... }

Toggle verification for a player account

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

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

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