PlayFab Authentication API

openapi: 3.0.3
info:
  version: '260922'
  title: PlayFab Authentication API
  description: The Authentication APIs provide a convenient way to convert classic authentication responses into entity authentication models.
    These APIs will provide you with the entity authentication token needed for subsequent Entity API calls. The game_server API is designed to
    create uniquely identifiable game_server entities. The game_server Entity token can be used to call Matchmaking Lobby and Pubsub for server
    scenarios.
  termsOfService: https://playfab.com/terms/
  contact:
    url: https://community.playfab.com/index.html
  license:
    name: Apache 2.0
    url: https://github.com/PlayFab/API_Specs/blob/master/LICENSE
servers:
- url: https://{titleId}.playfabapi.com
  variables:
    titleId:
      default: titleId
      description: Unique PlayFab title identifier.
tags:
- name: Authentication
  description: Authentication APIs
paths:
  /Authentication/GetEntityToken:
    post:
      operationId: GetEntityToken
      tags:
      - Authentication
      description: Method to exchange a legacy AuthenticationTicket or title SecretKey for an Entity Token or to refresh a still valid Entity
        Token.
      externalDocs:
        url: https://docs.microsoft.com/rest/api/playfab/authentication/authentication/getentitytoken
      security:
      - None: []
      x-requestDetails: This API must be called with X-SecretKey, X-Authentication or X-EntityToken headers. The header must still be valid and
        cannot be expired or revoked.If successful, it will issue a new entity token and emit the "entity_logged_in" PlayStream event.
      x-ms-docs-errors:
      - EncryptionKeyBroken
      - NoValidCertificateForAad
      parameters:
      - type: object
        description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves;
          the shape is unknown and is NOT a claim about the API.
        x-ae-placeholder: true
      responses:
        '200':
          description: ''
        '400':
          description: ''
  /Authentication/ValidateEntityToken:
    post:
      operationId: ValidateEntityToken
      tags:
      - Authentication
      description: 'Method for a server to validate a client provided EntityToken. Only callable by the title entity.


        Allowed entity token types: title'
      externalDocs:
        url: https://docs.microsoft.com/rest/api/playfab/authentication/authentication/validateentitytoken
      security:
      - EntityToken: []
      x-requestDetails: Given an entity token, validates that it hasn't expired or been revoked and will return details of the owner.
      parameters:
      - type: object
        description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves;
          the shape is unknown and is NOT a claim about the API.
        x-ae-placeholder: true
      responses:
        '200':
          description: ''
        '400':
          description: ''
  /GameServerIdentity/AuthenticateGameServerWithCustomId:
    post:
      operationId: AuthenticateGameServerWithCustomId
      tags:
      - Authentication
      description: 'Create a game_server entity token and return a new or existing game_server entity.


        Allowed entity token types: title'
      externalDocs:
        url: https://docs.microsoft.com/rest/api/playfab/authentication/authentication/authenticategameserverwithcustomid
      security:
      - EntityToken: []
      x-requestDetails: Create or return a game_server entity token. Caller must be a title entity.
      parameters:
      - type: object
        description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves;
          the shape is unknown and is NOT a claim about the API.
        x-ae-placeholder: true
      responses:
        '200':
          description: ''
        '400':
          description: ''
  /GameServerIdentity/Delete:
    post:
      operationId: Delete
      tags:
      - Authentication
      description: 'Delete a game_server entity.


        Allowed entity token types: title, game_server'
      externalDocs:
        url: https://docs.microsoft.com/rest/api/playfab/authentication/authentication/delete
      security:
      - EntityToken: []
      x-requestDetails: Delete a game_server entity. The caller can be the game_server entity attempting to delete itself. Or a title entity attempting
        to delete game_server entities for this title.
      parameters:
      - type: object
        description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves;
          the shape is unknown and is NOT a claim about the API.
        x-ae-placeholder: true
      responses:
        '200':
          description: ''
        '400':
          description: ''
components:
  schemas:
    ApiErrorWrapper:
      description: The basic wrapper around every failed API response
      type: object
      properties:
        code:
          description: Numerical HTTP code
          type: integer
        status:
          description: String HTTP code
          type: string
        error:
          description: Playfab error code
          type: string
        errorCode:
          description: Numerical PlayFab error code
          type: integer
        errorMessage:
          description: Description for the PlayFab errorCode
          type: string
        errorDetails:
          description: Detailed description of individual issues with the request object
          type: object
      required:
      - code
      - errorCode
    AuthenticateCustomIdRequest:
      description: Create or return a game_server entity token. Caller must be a title entity.
      type: object
      properties:
        CustomId:
          description: The customId used to create and retrieve game_server entity tokens. This is unique at the title level. CustomId must be
            between 32 and 100 characters.
          type: string
        CustomTags:
          description: The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).
          type: object
      required:
      - CustomId
      example:
        CustomId: 12345678123412341234123456789abc
    AuthenticateCustomIdResult:
      type: object
      properties:
        EntityToken:
          $ref: '#/components/schemas/EntityTokenResponse'
          description: The token generated used to set X-EntityToken for game_server calls.
          type: object
          x-isclass: true
        NewlyCreated:
          description: True if the account was newly created on this authentication.
          type: boolean
      required:
      - NewlyCreated
      example:
        EntityToken:
          EntityToken: Bw3YDMumgfsv45GKWxgUCF7DumqFnbFbVDQTyYcDrCpBavU3YDJJ47D388eyeDfZ
          TokenExpiration: '2022-01-26T07:24:12Z'
          Entity:
            Id: 3D00C64954
            Type: game_server
            TypeString: game_server
        NewlyCreated: true
    DeleteRequest:
      description: Delete a game_server entity. The caller can be the game_server entity attempting to delete itself. Or a title entity attempting
        to delete game_server entities for this title.
      type: object
      properties:
        CustomTags:
          description: The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).
          type: object
        Entity:
          $ref: '#/components/schemas/EntityKey'
          description: The game_server entity to be removed.
          type: object
          x-isclass: true
      required:
      - Entity
      example:
        Entity:
          Id: 3D00C64954
          Type: game_server
          TypeString: game_server
    EmptyResponse:
      type: object
      properties: {}
    EntityKey:
      description: Combined entity type and ID structure which uniquely identifies a single entity.
      type: object
      properties:
        Id:
          description: Unique ID of the entity.
          type: string
        Type:
          description: Entity type. See https://docs.microsoft.com/gaming/playfab/features/data/entities/available-built-in-entity-types
          type: string
      required:
      - Id
    EntityLineage:
      type: object
      properties:
        CharacterId:
          description: The Character Id of the associated entity.
          type: string
        GroupId:
          description: The Group Id of the associated entity.
          type: string
        MasterPlayerAccountId:
          description: The Master Player Account Id of the associated entity.
          type: string
        NamespaceId:
          description: The Namespace Id of the associated entity.
          type: string
        TitleId:
          description: The Title Id of the associated entity.
          type: string
        TitlePlayerAccountId:
          description: The Title Player Account Id of the associated entity.
          type: string
    EntityTokenResponse:
      type: object
      properties:
        Entity:
          $ref: '#/components/schemas/EntityKey'
          description: The entity id and type.
          type: object
          x-isclass: true
        EntityToken:
          description: The token used to set X-EntityToken for all entity based API calls.
          type: string
        TokenExpiration:
          description: The time the token will expire, if it is an expiring token, in UTC.
          type: string
      example:
        EntityToken: lS2hbYH1Gls1KbnlyozHSQBrF4zsq6q006ci9ijSNqQUiiO6xyCQtVrLjsXjdBJ
        TokenExpiration: '2022-01-26T07:24:12Z'
        Entity:
          Id: 174812abf712
          Type: title_player_account
          TypeString: title_player_account
    GetEntityTokenRequest:
      description: This API must be called with X-SecretKey, X-Authentication or X-EntityToken headers. The header must still be valid and cannot
        be expired or revoked.If successful, it will issue a new entity token and emit the "entity_logged_in" PlayStream event.
      type: object
      properties:
        CustomTags:
          description: The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).
          type: object
      example: {}
    GetEntityTokenResponse:
      type: object
      properties:
        Entity:
          $ref: '#/components/schemas/EntityKey'
          description: The entity id and type.
          type: object
          x-isclass: true
        EntityToken:
          description: The token used to set X-EntityToken for all entity based API calls.
          type: string
        TokenExpiration:
          description: The time the token will expire, if it is an expiring token, in UTC.
          type: string
      example:
        EntityToken: lS2hbYH1Gls1KbnlyozHSQBrF4zsq6q006ci9ijSNqQUiiO6xyCQtVrLjsXjdBJ
        TokenExpiration: '2022-01-26T07:24:12Z'
        Entity:
          Id: 174812abf712
          Type: title_player_account
          TypeString: title_player_account
    IdentifiedDeviceType:
      type: string
      enum:
      - Unknown
      - XboxOne
      - Scarlett
      - WindowsOneCore
      - WindowsOneCoreMobile
      - Win32
      - android
      - iOS
      - PlayStation
      - Nintendo
    LoginIdentityProvider:
      type: string
      enum:
      - Unknown
      - PlayFab
      - Custom
      - GameCenter
      - GooglePlay
      - Steam
      - XBoxLive
      - PSN
      - Kongregate
      - Facebook
      - IOSDevice
      - AndroidDevice
      - Twitch
      - WindowsHello
      - GameServer
      - CustomServer
      - NintendoSwitch
      - FacebookInstantGames
      - OpenIdConnect
      - Apple
      - NintendoSwitchAccount
      - GooglePlayGames
      - XboxMobileStore
      - King
      - BattleNet
    ValidateEntityTokenRequest:
      description: Given an entity token, validates that it hasn't expired or been revoked and will return details of the owner.
      type: object
      properties:
        CustomTags:
          description: The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).
          type: object
        EntityToken:
          description: Client EntityToken
          type: string
      required:
      - EntityToken
      example:
        EntityToken: 50c61b9065b27a124a400ee3b95d404313986969
    ValidateEntityTokenResponse:
      type: object
      properties:
        Entity:
          $ref: '#/components/schemas/EntityKey'
          description: The entity id and type.
          type: object
          x-isclass: true
        IdentifiedDeviceType:
          $ref: '#/components/schemas/IdentifiedDeviceType'
          description: The authenticated device for this entity, for the given login
          type: string
          x-isenum: true
        IdentityProvider:
          $ref: '#/components/schemas/LoginIdentityProvider'
          description: The identity provider for this entity, for the given login
          type: string
          x-isenum: true
        IdentityProviderIssuedId:
          description: The ID issued by the identity provider, e.g. a XUID on Xbox Live
          type: string
        Lineage:
          $ref: '#/components/schemas/EntityLineage'
          description: The lineage of this profile.
          type: object
          x-isclass: true
      example:
        Lineage:
          NamespaceId: '1679471093'
          TitleId: '26917491733'
          MasterPlayerAccountId: '1234567787392'
          TitlePlayerAccountId: '42434567785265'
        IdentityProvider: PlayFab
        IdentifiedDeviceType: XboxOne
        IdentityProviderIssuedId: '2533274790395904'
        Entity:
          Id: '42434567785265'
          Type: title_player_account
          TypeString: title_player_account
  securitySchemes:
    None:
      type: apiKey
      in: header
      name: None
      description: This API requires no authentication headers (usually provides one to other calls).
    SessionTicket:
      type: apiKey
      in: header
      name: X-Authorization
      description: This API requires a client session ticket, available from any Client Login function.
    SecretKey:
      type: apiKey
      in: header
      name: X-SecretKey
      description: This API requires a title secret key, available to title admins, from PlayFab Game Manager.
    EntityToken:
      type: apiKey
      in: header
      name: X-EntityToken
      description: This API requires an Entity Session Token, available from the Entity GetEntityToken method.
x-source:
  converted-from: https://raw.githubusercontent.com/PlayFab/API_Specs/master/Swagger/PlayFab/Authentication.swagger.json
  method: converted swagger 2.0 -> openapi 3.0.3 mechanically
  generated: '2026-11-05'