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.

Request

Header Parameters

user-agent User-Agent
x-rh-client-addr X-Rh-Client-Addr

Possible values: <= 32 characters

IP Address hint

application/json

Body

required

grant_type GrantType (string)required

Possible values: [anon, google, apple, refresh, epic, xboxlive, ps4_v1, ps4_v3, ps5_v3, nintendo, nintendo_switch, steam, basic, rallyhere, client_credentials]

Supported grant types for V1 Login Flow

portal_access_token Portal Access Token (string)

Token or secret used to authenticate the provided grant type

portal_display_name Portal Display Name (string)

Some grant types support client-provided names

portal_parent_access_token Portal Parent Access Token (string)

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

portal_parent_display_name Portal Parent Display Name (string)

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

include_refresh Include Refresh (boolean)

Indicates if the client wants a refresh token returned

accept_eula Accept Eula (boolean)

If true, the user has accepted the EULA

accept_tos Accept Tos (boolean)

If true, the user has accepted the Terms of Service

accept_privacy_policy Accept Privacy Policy (boolean)

If true, the user has accepted the Privacy Policy

Responses

200

Successful Response

application/json

Schema

Schema

portal_parent_auth_result

object

Portal user info

platform Platform (string)required

Possible values: [Anon, Basic, XboxLive, PSN, NintendoNAID, NintendoSwitch, NintendoPPID, Google, GooglePlay, Apple, Epic, Steam, Amazon, Twitch, RallyHere, LegacyName]

Platform for the user

portal_id Portal (integer)requireddeprecated

Possible values: [2, 4, 5, 9, 10, 11, 13, 14, 16, 22, 24, 26, 27, 28, 33]

Portal ID. DEPRECATED use platform instead

portal_user_id Portal User Id (string)required

Platform User ID

display_name Display Name (string)required

Display name

device_type DeviceType (string)

Possible values: [pc, xbox_series, xbox_one, web]

Platform-verified device type of the login

permissions string[]

Default value: ``

List of permissions for this user.

restrictions

object[]

List of restrictions on this player

Array [

type RestrictionType (string)required

Possible values: [account_ban, account_lockout, account_pending_deletion, account_deny_auth]

Restrictions that can be applied to a player. Resitrictions are applied to a player by an admin and often types indicates that the player is banned.

reason RestrictionReasonCode (string)

Possible values: [cheating_autodetected, speedhack_autodetect, other, cheating_observed, cheating_reported_by_player, threats, language, griefing, fraud, revoke_failed, unknown, guardian, issuer_process, account_migration, user_request, maintenance, pending_deletion]

An enumeration.

expiration date-time

Date the restriction expires. Null means the restriction is permanent

]

active_player_id Active Player Id (integer)deprecated

Active player ID. DEPRECATED use active_player_uuid instead

active_player_uuid uuid

Active player UUID

platform Platform (string)

Possible values: [Anon, Basic, XboxLive, PSN, NintendoNAID, NintendoSwitch, NintendoPPID, Google, GooglePlay, Apple, Epic, Steam, Amazon, Twitch, RallyHere, LegacyName]

An enumeration.

portal_id Portal Id (integer)deprecated

Portal ID DEPRECATED use platform instead

portal_user_id Portal User Id (string)

Portal user ID

display_name Display Name (string)

Display name

role_id Role Id (integer)

Role ID

person_id uuid

Person ID

access_token Access Token (string)

Access token that can be used for future requests

refresh_token Refresh Token (string)

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

publisher_uuid uuidrequireddeprecated

Publisher UUID

tenant_uuid uuidrequireddeprecated

Tenant UUID

config_elector_uuid uuidrequireddeprecated

Config elector UUID

client_uuid uuidrequireddeprecated

Client UUID

client_id Client Id (string)required

Client ID

token_type Token Type (string)required

Token type

expires_in Expires In (integer)

Result access token expiration time in seconds

Example (from schema)

{
  "portal_parent_auth_result": {
    "platform": "Anon",
    "portal_user_id": "string",
    "display_name": "string",
    "device_type": "pc"
  },
  "permissions": [
    "string"
  ],
  "restrictions": [
    {
      "type": "account_ban",
      "reason": "cheating_autodetected",
      "expiration": "2024-07-29T15:51:28.071Z"
    }
  ],
  "active_player_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "platform": "Anon",
  "portal_user_id": "string",
  "display_name": "string",
  "role_id": 0,
  "person_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "access_token": "string",
  "refresh_token": "string",
  "client_id": "string",
  "token_type": "string",
  "expires_in": 0
}

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

application/json

Schema

Schema

auth_success Auth Success (boolean)

Default value: true

error_code Error Code (string)required
desc Desc (string)required
needs_eula Needs Eula (boolean)

Whether the user needs to accept the End User License Agreement

needs_tos Needs Tos (boolean)

Whether the user needs to accept the Terms of Service

needs_privacy_policy Needs Privacy Policy (boolean)

Whether the user needs to accept the Privacy Policy

Example (from schema)

{
  "auth_success": true,
  "error_code": "string",
  "desc": "string",
  "needs_eula": false,
  "needs_tos": false,
  "needs_privacy_policy": false
}

422

Validation Error

application/json

Schema

Schema

detail

object[]

Array [

loc

object[]

required

Array [

anyOf

MOD1

string

MOD2

integer

]

msg Message (string)required

type Error Type (string)required

]

Example (from schema)

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

503

The service is currently unavailable. Please try again later.

Response Headers

• Retry-After

  int

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

application/json

Schema

Schema

auth_success Auth Success (boolean)

Default value: true

error_code Error Code (string)required
desc Desc (string)required

Example (from schema)

{
  "auth_success": true,
  "error_code": "string",
  "desc": "string"
}

Loading...