openapi: 3.0.3
info:
  title: Appcharge Assets Authentication API
  version: 1.0.0
  description: Appcharge is a monetization platform for mobile games, providing a direct-to-consumer (D2C) web store, mobile Checkout SDK, and Payment Links so publishers can sell in-game offers outside the app stores. This API covers checkout sessions, refunds, coupons and promo codes, price localization, financial and analytics reporting, web store offers (bundles, daily bonuses, rolling/special offers, progress bars, reward calendars, triggered popups), offer components (products, badges, offer designs), game-portal content, media assets, translations, and player personalization/authentication callbacks. Authentication uses the x-publisher-token header; webhooks are signed with an HMAC-SHA256 signature.
  contact:
    name: Appcharge Developer Support
    url: https://docs.appcharge.com/
  x-apievangelist-source: https://docs.appcharge.com/api-reference (Mintlify embedded OpenAPI fragments)
  x-apievangelist-method: searched
  x-apievangelist-generated: '2026-07-17'
servers:
- url: https://api.appcharge.com
  description: Production
- url: https://api-sandbox.appcharge.com
  description: Sandbox
tags:
- name: Authentication
paths:
  /{YOUR_AUTHENTICATE_PLAYER_ENDPOINT}:
    post:
      tags:
      - Authentication
      summary: Authenticate Player
      description: "<Note> This is a callback API. Appcharge calls this endpoint on your server when specific events occur. </Note> \n\n Notifies your system to authenticate a player in your web store. <br /> <br /> 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. <br /> <br /> 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. \n\n **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. \n\n **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: \n + `none`: No error message is provided. \n + `plainText`: A basic error message in plain text. \n + `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
  /{YOUR_INITIATE_GAME_AUTH_ENDPOINT}:
    post:
      tags:
      - Authentication
      summary: Initiate Game Auth
      description: <Warning> This API endpoint is only relevant for the Game Redirect Login method. </Warning> <Note> This is a callback API. Appcharge calls this endpoint on your server when specific events occur. </Note> Notifies your system to initiate an authentication session in your game. <br /> <br /> Appcharge calls this endpoint when a player attempts to log in via [Game Redirect Login](/../../guides/webstore/player-authentication/game-redirect-login/about-game-redirect-login). Your server responds with either the data needed to redirect the player to your game for authentication, or an error.
      operationId: game-authentication-endpoint
      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:
                device:
                  type: string
                  enum:
                  - DESKTOP
                  - APPCHARGE
                  description: "Device the player used to log in. \n \n  + `DESKTOP`: PCs and laptops. \n + `APPCHARGE`: Mobile."
                  example: DESKTOP
                date:
                  type: string
                  format: date-time
                  description: Date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
                  example: '2023-11-07T05:31:56Z'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - deepLink
                - accessToken
                properties:
                  deepLink:
                    type: string
                    description: Deeplink for redirecting the player to your game for authentication.
                    example: https://my-awesome-game/2298/bv45d674?key=549bc5151667f6216629efe46vf7bacd2812d82298
                  accessToken:
                    type: string
                    description: Player access token.
                    example: 9ac8883227afa33412197b
                  desktopAutoRedirect:
                    type: boolean
                    default: false
                    description: 'Whether players logging into the web store on desktop are redirected to the deepLink URL instead of being shown a QR code.


                      When `false` or omitted, these players see a QR code of the deeplink and must scan it with their phone to open the game.'
                    example: true
        '400':
          description: Invalid signature
        '401':
          description: Unauthorized
        '403':
          description: Parameters not correct
components:
  securitySchemes:
    PublisherTokenAuth:
      type: apiKey
      in: header
      name: x-publisher-token
      description: Publisher token, as displayed in the Publisher Dashboard.