> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appcharge.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Authenticate Player Callback
> > **Note:** This is a callback API. Appcharge calls this endpoint on your server when specific events occur.
Notifies your system to authenticate a player in your web store.
Appcharge calls this endpoint when a player attempts to log in to your web store using one of the configured login methods. Your server identifies the player and responds with either the player data or an authentication error.
If the response indicates a successful authentication, the player is logged in to the web store.
```bash Authenticate Game Redirect Login theme={"system"}
curl -X POST \
'https://{YOUR_AUTHENTICATE_PLAYER_ENDPOINT}' \
-H 'Content-Type: application/json' \
-H 'x-publisher-token: ' \
-H 'signature: ' \
-d '{
"authMethod": "otp",
"date": "2025-10-21T14:17:27.329Z",
"appId": "NA",
"playerLocation": {
"countryCode2": "US",
"state": "FL"
},
"otp": {
"playerCode": "974018",
"accessToken": "9ac888fa33412197b"
},
"os": "ios",
"sessionId": "2e55b3fc-31ef-6dd7-8161-8aeb376b3a23"
}'
```
```bash Authenticate SSO Login theme={"system"}
curl -X POST \
'https://{YOUR_AUTHENTICATE_PLAYER_ENDPOINT}' \
-H 'Content-Type: application/json' \
-H 'x-publisher-token: ' \
-H 'signature: ' \
-d '{
"authMethod": "google",
"token": "sdfddtt7",
"date": "2024-07-21T14:17:27.329Z",
"appId": "611392880818819",
"playerLocation": {
"countryCode2": "US",
"state": "NY"
},
"os": "android",
"utmSource": "Instagram",
"utmCampaign": "spring_sale.",
"sessionId": "2e55b3fc-31ef-6dd7-8161-8aeb376b3a23"
}'
```
```json Authenticate Game Redirect Login theme={"system"}
{
"status": "valid",
"playerProfileImage": "",
"publisherPlayerId": "986222719",
"playerName": "Mary Littlelamb",
"playerOverrideCountry": "CA",
"sessionMetadata": {
"abTest": "group1",
"locale": "en-CA"
}
}
```
```json Authenticate SSO Login theme={"system"}
{
"status": "valid",
"playerProfileImage": "https://scontent-iad4-1.xx.fbcdn.net/v/t6.30597-1/84628273_176159830277856_972693363922829312_n.jpg?stp=c379.0.1290.1290a_cp0_dst-jpg_s50x50_tt6&ccb=1-7",
"publisherPlayerId": "vip2247691",
"playerName": "Jim Cardashian",
"sessionMetadata": {
"abTest": "group1",
"locale": "en-US"
}
}
```
```json Login Failed theme={"system"}
{
"status": "Invalid",
"publisherErrorMessageType": "plainText",
"publisherErrorMessage": "Lost internet connection.",
"publisherErrorMessageTitle": "Whoops! Login Failed."
}
```
## OpenAPI
````yaml openapi-authenticate-player-callback.json POST /{YOUR_AUTHENTICATE_PLAYER_ENDPOINT}
openapi: 3.1.0
info:
title: Authenticate Player
version: 1.0.0
description: API to authenticate players.
servers: []
security: []
paths:
/{YOUR_AUTHENTICATE_PLAYER_ENDPOINT}:
post:
tags:
- Authentication
summary: Authenticate Player
description: >-
This is a callback API. Appcharge calls this endpoint on your
server when specific events occur.
Notifies your system to authenticate a player in your web store.
Appcharge calls this endpoint when a player attempts to log in to your web store using one of the configured login methods. Your server identifies the player and responds with either the player data or an authentication error.
If the response indicates a successful authentication, the player is logged in to the web store.
operationId: authenticate-player
parameters:
- name: x-publisher-token
in: header
description: Publisher token.
schema:
type: string
- name: signature
in: header
description: The signed payload.
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
authMethod:
type: string
description: |-
Authentication method the player used.
**Note:** If the player logged in using either Pre-Authenticated Login or Game Redirect Login, Appcharge sends the value `otp`.
enum:
- facebook
- apple
- google
- userToken
- userPassword
- otp
example: facebook
token:
type:
- string
- 'null'
description: >-
Authentication token. Used for SSO Login and Player ID
Login.
example: sdfddtt7
date:
type: string
format: date-time
description: UTC time when the player tried to log in.
example: '2024-07-21T14:17:27.329Z'
appId:
type: string
description: >-
App ID in the Publisher Dashboard. Used for the SSO Login
method. If no app ID is available, Appcharge sends `"NA"`.
example: '611392880818819'
userName:
type:
- string
- 'null'
description: >-
Username the player entered when logging in to the web
store.
example: expertgamer1979
password:
type:
- string
- 'null'
description: >-
Password the player entered when logging in to the web
store.
example: 732hf8820pk!
otp:
type:
- object
- 'null'
description: |-
Additional authentication tokens provided by your game.
**Note:** This field is sent only if the player logged in using Pre-Authenticated Login or Game Redirect Login.
properties:
playerCode:
type: string
description: The 4 or 6 digit code used for verifying the player.
example: '974018'
accessToken:
type: string
description: Player access token.
example: 9ac888fa33412197b
os:
type: string
enum:
- ios
- android
- web
description: Operating system the player used to log in.
example: android
utmSource:
type: string
description: >-
Source of the traffic. This is where the player came from
before reaching the store.
example: Facebook
utmMedium:
type: string
description: Marketing channel used to bring in the traffic.
example: email
utmCampaign:
type: string
description: Marketing campaign identifier associated with the traffic.
example: spring_sale.
sessionId:
type: string
description: Session ID.
example: 2e55b3fc-31ef-6dd7-8161-8aeb376b3a23
playerLocation:
type: object
description: Location of the player.
properties:
countryCode2:
type: string
description: >-
Two-letter country code in [ISO-3166
alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
format. Example: `US`
example: US
state:
type: string
description: 'Two-letter state code. Example: `NY`'
example: NY
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
required:
- status
- publisherPlayerId
- playerName
properties:
status:
type: string
description: >-
The status of the player authentication. If you pass a
value other than `valid`, the API fails.
enum:
- valid
example: valid
playerProfileImage:
type: string
description: >-
Player profile image. If no image is available, an empty
string must be provided. In this case, a default image is
displayed.
example: >-
https://scontent-iad4-1.xx.fbcdn.net/v/t6.30597-1/84628273_176159830277856_972693363922829312_n.jpg?stp=c379.0.1290.1290a_cp0_dst-jpg_s50x50_tt6&ccb=1-7
publisherPlayerId:
type: string
description: Player ID.
example: vip2247691
playerName:
type: string
description: Player name.
example: Jim Cardashian
sessionMetadata:
type: object
description: >-
An object for passing data related to the player's
session. It is returned in the [Grant Award
Callback](/../../api-reference/checkout/awards/grant-award-callback),
and if enabled, the [Personalization
API](/../../api-reference/webstore/personalization/introduction).
example:
abTest: group1
locale: en-US
publisherErrorMessageType:
type: string
enum:
- none
- plainText
- enrichedText
description: |-
Error message type. Supported values:
+ `none`: No error message is provided.
+ `plainText`: A basic error message in plain text.
+ `enrichedText`: A formatted error message in MD format that may contain additional styling or elements.
example: plainText
publisherErrorMessage:
type: string
description: Error message.
example: Lost internet connection.
publisherErrorMessageTitle:
type: string
description: >-
Error message title displayed to players when a login
attempt fails.
example: Whoops! Login Failed.
playerOverrideCountry:
type: string
description: >-
Overrides the player's detected location for pricing
purposes. Use when the player's country of origin differs
from their detected country. Must be a two-letter country
code in [ISO-3166
alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
format.
example: CA
````