Skip to content
RallyHere Docs

Login

POST
/users/v1/login

This endpoint is used to authenticate a user and retrieve an access token for use with other RallyHere APIs.

This endpoint supports user-based authentication for a variety of platforms.

Authorizations

Parameters

Header Parameters

user-agent
string
x-forwarded-for
string

Request Body required

object
grant_type
required

The grant type to use for authentication

string
Allowed values: anon google apple refresh epic xboxlive ps4_v1 ps4_v3 ps5_v3 nintendo nintendo_switch steam basic rallyhere client_credentials
portal_access_token

Token or secret used to authenticate the provided grant type

string
""
portal_display_name

Some grant types support client-provided names

string
""
portal_parent_access_token

Some grant types have 2 tier authentication and require a second token/secret

string
""
portal_parent_display_name

Some grant types have 2 tier authentication and support a second display name

string
""
include_refresh

Indicates if the client wants a refresh token returned

boolean
accept_eula

If true, the user has accepted the EULA

boolean
accept_tos

If true, the user has accepted the Terms of Service

boolean
accept_privacy_policy

If true, the user has accepted the Privacy Policy

boolean

Responses

200

Successful Response

Login result

object
portal_parent_auth_result

Parent portal auth result

object
platform
required

Platform for the user

string
Allowed values: Anon Basic XboxLive PSN NintendoNAID NintendoSwitch NintendoPPID Google GooglePlay Apple Epic Steam Amazon Twitch RallyHere LegacyName
portal_id
required

Portal ID. DEPRECATED use platform instead

integer
portal_user_id
required

Platform User ID

string
display_name
required

Display name

string
permissions

List of permissions for this user.

Array<string>
default:
restrictions

List of restrictions on this player

Array<object>
default:

Restriction applied to a player

object
type
required

Type of restriction

string
Allowed values: account_ban account_lockout account_pending_deletion account_deny_auth
reason

Reason the restriction was applied

string
expiration

Date the restriction expires. Null means the restriction is permanent

string format: date-time
active_player_id

Active player ID. DEPRECATED use active_player_uuid instead

integer
active_player_uuid

Active player UUID

string format: uuid
platform

Platform

string
Allowed values: Anon Basic XboxLive PSN NintendoNAID NintendoSwitch NintendoPPID Google GooglePlay Apple Epic Steam Amazon Twitch RallyHere LegacyName
portal_id

Portal ID DEPRECATED use platform instead

integer
portal_user_id

Portal user ID

string
display_name

Display name

string
role_id

Role ID

integer
person_id

Person ID

string format: uuid
access_token

Access token that can be used for future requests

string
""
refresh_token

Refresh token that can be used to refresh authentication for a new access token

string
publisher_uuid
required

Publisher UUID

string format: uuid
tenant_uuid
required

Tenant UUID

string format: uuid
config_elector_uuid
required

Config elector UUID

string format: uuid
client_uuid
required

Client UUID

string format: uuid
client_id
required

Client ID

string
token_type
required

Token type

string
expires_in

Result access token expiration time in seconds

integer

403

User authentication failed. See error code and description for further details.

Error Codes:

  • internal_error - An internal error occurred. The request may succeed if retried. If not, contact an administrator.
  • no_redirects_configured - No redirect urls setup for oauth.
  • redirect_uri_does_not_match - Redirect URI does not match a configured value.
  • error_occurred_during_exchange - An error occurred while exchanging a code for token.
  • failed_to_verify_state - Failed to verify the state associated with the request.
  • failed_to_save_state - Error occurred saving the state.
  • failed_to_save_tokens - Problem saving tokens. Contact an administrator
  • too_many_users - Account has too many users associated with it. Contact an administrator
  • user_auth_restricted - Authentication for this user has been restricted
  • user_needs_agreements - User has not accepted all required agreements. See response for list of agreements required
  • error_retrieving_player_results - Error retrieving player results
  • failed_to_retrieve_roles - Failed to retrieve roles
  • client_credentials_invalid - Client Credentials provided to authentication attempt were invalid
  • authentication_limited - Authentication is currently limited to accounts that are already logged in. Please try again later
  • authentication_locked - Authentication is currently locked. Please try again later
  • invalid_grant_type - Grant Type {grant_type} is not supported
  • user_auth_disabled - User authentication is not permitted for this policy
  • client_auth_disabled - Client authentication is not permitted for this policy
  • amazon_disabled - Amazon authentication is currently disabled
  • amazon_token_empty - Amazon access token is empty
  • amazon_invalid_access_token - Amazon access token is invalid
  • amazon_token_exchange_failed - Problem exchanging code for token with Amazon
  • anon_disabled - Anon authentication is currently disabled
  • anon_token_empty - Anon access token is empty
  • apple_disabled - Apple authentication is currently disabled
  • apple_token_empty - Apple access token is empty
  • apple_failed_key_lookup - Failed to retrieve keys from Apple
  • apple_token_exchange_failed - Problem exchanging code for token with Apple
  • apple_token_key_not_valid - public key not found
  • apple_token_not_valid - Apple access token is not valid
  • authorization_code_not_found - Authorization code not found or expired
  • basic_disabled - Basic authentication is currently disabled
  • basic_token_empty - Basic access token is empty
  • basic_auth_incorrect_format - Basic auth should be formatted like USERNAME:PASSWORD
  • basic_auth_credentials_not_found - Basic auth credentials not found
  • developer_api_disabled - Developer API authentication is currently disabled
  • developer_api_token_empty - Developer API access token is empty
  • developer_api_token_invalid - Developer API access token is invalid or expired
  • epic_disabled - Epic authentication is currently disabled
  • epic_token_empty - Epic access token is empty
  • epic_v1_token_key_id_invalid - Epic v1 token contains an invalid key id
  • epic_v1_token_invalid - Epic v1 token is invalid
  • epic_v2_keys_not_available - Epic v2 keys are not available. Please contact an administrator
  • epic_v2_token_invalid - Epic v2 token is invalid
  • epic_oauth_token_exchange_failed - Problem exchanging code for token with Epic
  • google_disabled - Google authentication is currently disabled
  • google_token_empty - Google access token is empty
  • google_keys_not_available - Google keys are not available. Please contact an administrator
  • google_token_not_valid - Google access token is not valid
  • google_token_exchange_failed - Problem exchanging code for token with Google
  • nintendo_disabled - Nintendo authentication is currently disabled
  • nintendo_token_empty - Nintendo access token is empty
  • nintendo_env_credentials_not_found - Nintendo environment credentials not found
  • nintendo_access_token_not_valid - Nintendo access token is not valid
  • nintendo_no_environment_matches_env_id - Nintendo environment not found for given environment ID
  • nintendo_retrieve_client_credentials_failed - Problem retrieving client credentials from Nintendo. This commonly occurs while converting between NAID and PPID.
  • nintendo_ppid_conversion_failed - error during PPID conversion
  • nintendo_ppid_conversion_too_many_accounts_found - too many accounts found during PPID conversion
  • nintendo_ppid_conversion_no_accounts_found - no accounts found during PPID conversion
  • nintendo_ppid_missing - PPID is missing for user
  • nintendo_ppid_key_not_valid - Nintendo access token key is not valid
  • nintendo_service_key_url_not_found - Nintendo service key url not found. This usually indicates that the corresponding Nintendo environment has a mismatch between Nintendo account URL and Nintendo Service Account URL.
  • nintendo_service_access_token_not_valid - Nintendo service access token is not valid
  • nintendo_service_access_token_for_wrong_app - Nintendo service access token is for the wrong app
  • nintendo_oauth_env_not_found - Nintendo oauth environment not found. Check that the environment is configured correctly.
  • nintendo_token_exchange_failed - Problem exchanging code for token with Nintendo
  • ps4_v1_disabled - PS4 v1 authentication is currently disabled
  • ps4_v1_token_empty - PS4 v1 access token is empty
  • ps4_v1_token_expired - PS4 v1 access token is expired
  • ps4_v1_token_exchange_failed - Problem exchanging code for token with PS4
  • ps4_v1_id_token_request_failed - Problem requesting id token from PS4
  • ps4_v1_id_token_not_valid - PS4 v1 id token is not valid
  • ps4_v1_token_details_disabled - PS4 v1 token details are disabled
  • ps4_v1_token_details_request_failed - Problem requesting token details from PS4
  • ps4_v3_disabled - PS4 v3 authentication is currently disabled
  • ps4_v3_token_details_disabled - PS4 v3 token details are disabled
  • ps4_v3_token_empty - PS4 v3 access token is empty
  • ps4_v3_id_token_request_failed - Problem requesting id token from PS4
  • ps4_v3_id_token_not_valid - PS4 v3 id token is not valid
  • ps5_v3_disabled - PS5 v3 authentication is currently disabled
  • ps5_v3_token_details_disabled - PS5 v3 token details are disabled
  • ps5_v3_token_empty - PS5 v3 access token is empty
  • ps5_v3_id_token_request_failed - Problem requesting id token from PS5
  • ps5_v3_id_token_not_valid - PS5 v3 id token is not valid
  • psn_environment_permission_denied - PSN Environment permission was denied. This usually means that the Client ID/Secret do not match. This error can also occur for sp-int or prod-qa if the environment is not whitelisted to access the PSN environment.
  • refresh_disabled - Refresh authentication is currently disabled
  • refresh_token_empty - Refresh token is empty
  • refresh_token_not_found - Refresh token was not found or has expired
  • refresh_token_invalid_user - Refresh token refrences invalid user
  • refresh_token_client_id_mismatch - Client ID for new token request did not match original token
  • steam_disabled - Steam authentication is currently disabled
  • steam_token_empty - Steam code (Ticket) is empty
  • steam_token_exchange_failed - Problem exchanging code (ticket) for token with Steam
  • steam_user_vacbanned - User is VAC banned
  • steam_user_publisherbanned - User is publisher banned
  • steam_user_offline - User is reporting offline to Steam, causing all Steam tickets to invalidate
  • steam_token_invalid - Steam code (Ticket) was reported as invalid by Steam
  • steam_token_for_wrong_app - Steam code (Ticket) is for a different Steam Application
  • twitch_disabled - Twitch authentication is currently disabled
  • twitch_token_empty - Twitch access token is empty
  • twitch_token_invalid - Twitch access token is not valid
  • twitch_keys_not_available - Twitch keys are not available. Please contact an administrator
  • twitch_token_exchange_failed - Problem exchanging code for token with Twitch
  • xbox_disabled - Xbox authentication is currently disabled
  • xbox_xsts_token_empty - Xbox XSTS token is empty
  • xbox_xsts_token_invalid - Xbox XSTS token is not valid
  • xbox_xtoken_invalid - Xbox XToken is not valid
  • xbox_access_token_request_failed - Problem requesting access token from Xbox
  • xbox_xsts_token_exchange_failed - Problem exchanging access token for XSTS token with Xbox
  • xbox_xtoken_exchange_failed - Problem exchanging XSTS token for XToken with Xbox

Error message for when a user has not agreed to the EULA, TOS, or Privacy Policy

object
auth_success
boolean
default: true
error_code
required
string
desc
required
string
needs_eula

Whether the user needs to accept the End User License Agreement

boolean
needs_tos

Whether the user needs to accept the Terms of Service

boolean
needs_privacy_policy

Whether the user needs to accept the Privacy Policy

boolean

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string

503

The service is currently unavailable. Please try again later.

object
auth_success
boolean
default: true
error_code
required
string
desc
required
string

Headers

Retry-After
int

indicates how long the user agent should wait before making a follow-up request