openapi: 3.0.3
info:
  title: Minecraft Services API
  description: >-
    Microsoft-managed Minecraft Services API (api.minecraftservices.com).
    Covers authenticated player profile management, name change, skin and
    cape management, player attributes (chat, friends, profanity filter),
    privacy blocklist, friends graph, presence reporting, signature
    keypair issuance, public-key publication for chat signature
    verification, and player entitlement / ownership checks. Most
    endpoints require a Minecraft Bearer access token obtained via the
    Xbox Live -> XSTS -> Minecraft authentication chain.
  version: '1.0.0'
  contact:
    name: Mojang Studios
    url: https://www.minecraft.net
  license:
    name: Mojang Brand and Asset Usage Guidelines
    url: https://www.minecraft.net/en-us/usage-guidelines
  x-generated-from: documentation
  x-last-validated: '2026-05-30'
servers:
  - url: https://api.minecraftservices.com
    description: Microsoft / Minecraft Services API (production)
tags:
  - name: Authentication
    description: Exchange Xbox Live tokens for Minecraft access tokens
  - name: Identity
    description: Player UUID and username lookup
  - name: Profile
    description: Authenticated profile and name management
  - name: Skins
    description: Skin selection, upload, and reset
  - name: Capes
    description: Cape selection and visibility
  - name: Attributes
    description: Profanity filter, friends, chat preferences
  - name: Blocklist
    description: Player privacy blocklist
  - name: Friends
    description: Friends graph (list, add, remove)
  - name: Presence
    description: Online / playing presence reporting
  - name: Keys
    description: Signature keypairs and Mojang public keys
  - name: Entitlements
    description: Account ownership and entitlement checks
paths:
  /authentication/login_with_xbox:
    post:
      operationId: loginWithXbox
      summary: Login With Xbox
      description: >-
        Exchange an XSTS identity token for a Minecraft Bearer access token.
        First step after completing the Xbox Live authentication chain.
      tags:
        - Authentication
      requestBody:
        required: true
        description: XSTS identity token wrapped in Mojang's expected envelope.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XboxLoginRequest'
      responses:
        '200':
          description: Minecraft access token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MinecraftAccessToken'
        '401':
          description: Identity token rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /minecraft/profile/lookup/name/{username}:
    get:
      operationId: lookupProfileByName
      summary: Lookup Profile by Name
      description: Modern equivalent of the legacy api.mojang.com username-to-UUID lookup.
      tags:
        - Identity
      parameters:
        - name: username
          in: path
          required: true
          description: Case-insensitive Minecraft username.
          example: jeb_
          schema:
            type: string
      responses:
        '200':
          description: Profile match.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '404':
          description: Username not currently in use.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /minecraft/profile/lookup/{uuid}:
    get:
      operationId: lookupProfileByUuid
      summary: Lookup Profile by UUID
      description: Resolve a Minecraft username from a player UUID.
      tags:
        - Identity
      parameters:
        - name: uuid
          in: path
          required: true
          description: Player UUID (hyphenated or unhyphenated).
          example: 853c80ef3c3749fdaa49938b674adae6
          schema:
            type: string
            pattern: ^[0-9a-fA-F-]{32,36}$
      responses:
        '200':
          description: Profile match.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '404':
          description: UUID has no matching profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /minecraft/profile/lookup/bulk/byname:
    post:
      operationId: lookupProfilesBulkByName
      summary: Lookup Profiles Bulk by Name
      description: Resolve up to ten usernames to profiles in a single request.
      tags:
        - Identity
      requestBody:
        required: true
        description: JSON array of up to ten usernames.
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              maxItems: 10
              items:
                type: string
              example:
                - jeb_
                - Dinnerbone
                - Notch
      responses:
        '200':
          description: Resolved profiles.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Profile'
        '400':
          description: Empty array or more than ten usernames.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /minecraft/profile:
    get:
      operationId: getAuthenticatedProfile
      summary: Get Authenticated Profile
      description: >-
        Return the signed-in player's own profile including UUID, name, owned
        skins, and owned capes.
      tags:
        - Profile
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Authenticated profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticatedProfile'
        '401':
          description: Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /minecraft/profile/namechange:
    get:
      operationId: getNameChangeInfo
      summary: Get Name Change Info
      description: >-
        Returns the player's name-change cooldown state — last-change date,
        creation date, and whether a change is currently allowed.
      tags:
        - Profile
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Name-change information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameChangeInfo'
        '401':
          description: Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /minecraft/profile/name/{name}/available:
    get:
      operationId: checkNameAvailability
      summary: Check Name Availability
      description: >-
        Check whether a desired username is available, duplicate, or
        otherwise not allowed. Rate-limited to roughly 20 requests per five
        minutes per account.
      tags:
        - Profile
      security:
        - bearerAuth: []
      parameters:
        - name: name
          in: path
          required: true
          description: Candidate username.
          example: NewName123
          schema:
            type: string
      responses:
        '200':
          description: Availability response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameAvailability'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /minecraft/profile/name/{name}:
    put:
      operationId: changeName
      summary: Change Name
      description: Change the authenticated player's username.
      tags:
        - Profile
      security:
        - bearerAuth: []
      parameters:
        - name: name
          in: path
          required: true
          description: New username.
          example: NewName123
          schema:
            type: string
      responses:
        '200':
          description: Updated profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticatedProfile'
        '400':
          description: Invalid name supplied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Name already taken or change not currently allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /minecraft/profile/skins:
    post:
      operationId: changeSkin
      summary: Change Skin
      description: >-
        Set the player's active skin. Accepts either a URL pointing to the
        skin image (JSON body) or a multipart upload of the image file.
      tags:
        - Skins
      security:
        - bearerAuth: []
      requestBody:
        required: true
        description: Skin variant plus either a URL or an uploaded image file.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeSkinRequest'
          multipart/form-data:
            schema:
              type: object
              required:
                - variant
                - file
              properties:
                variant:
                  type: string
                  enum:
                    - classic
                    - slim
                  example: classic
                file:
                  type: string
                  format: binary
                  description: PNG skin image upload.
      responses:
        '200':
          description: Updated profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticatedProfile'
        '400':
          description: Invalid skin payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /minecraft/profile/skins/active:
    delete:
      operationId: resetSkin
      summary: Reset Skin
      description: Reset the player's skin to the default Minecraft skin (Steve / Alex).
      tags:
        - Skins
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Updated profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticatedProfile'
        '401':
          description: Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /minecraft/profile/capes/active:
    put:
      operationId: showCape
      summary: Show Cape
      description: Set a cape (by UUID) as the player's active cape.
      tags:
        - Capes
      security:
        - bearerAuth: []
      requestBody:
        required: true
        description: Cape selection.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CapeSelection'
      responses:
        '200':
          description: Updated profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticatedProfile'
        '400':
          description: Player does not own the requested cape.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: hideCape
      summary: Hide Cape
      description: Hide the player's currently active cape.
      tags:
        - Capes
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Updated profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticatedProfile'
        '401':
          description: Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /player/attributes:
    get:
      operationId: getPlayerAttributes
      summary: Get Player Attributes
      description: >-
        Returns the player's account attributes: privileges, profanity filter
        preferences, friends preferences, chat settings, and ban / suspension
        status.
      tags:
        - Attributes
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Player attributes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerAttributes'
        '401':
          description: Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: updatePlayerAttributes
      summary: Update Player Attributes
      description: Update the player's profanity filter and friends preferences.
      tags:
        - Attributes
      security:
        - bearerAuth: []
      requestBody:
        required: true
        description: Patch payload (only changed sections need be supplied).
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlayerAttributesUpdate'
      responses:
        '200':
          description: Updated attributes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerAttributes'
        '400':
          description: Invalid attribute payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /privacy/blocklist:
    get:
      operationId: getBlocklist
      summary: Get Blocklist
      description: Return the authenticated player's UUID-keyed blocklist.
      tags:
        - Blocklist
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Blocklist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Blocklist'
        '401':
          description: Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /friends:
    get:
      operationId: getFriends
      summary: Get Friends
      description: >-
        Return the authenticated player's friends list plus incoming and
        outgoing friend requests. Supports If-None-Match for ETag caching.
      tags:
        - Friends
      security:
        - bearerAuth: []
      parameters:
        - name: If-None-Match
          in: header
          required: false
          description: Conditional ETag — return 304 if unchanged.
          example: '"a1b2c3"'
          schema:
            type: string
      responses:
        '200':
          description: Friends list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FriendsList'
        '304':
          description: Not modified — supplied ETag still current.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateFriends
      summary: Update Friends
      description: Add or remove a friend by profile name or UUID.
      tags:
        - Friends
      security:
        - bearerAuth: []
      requestBody:
        required: true
        description: Friend update payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FriendUpdateRequest'
      responses:
        '200':
          description: Updated friends list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FriendsList'
        '400':
          description: Constraint violation (self-add, blocked, missing, etc.).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Player has friends disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /presence:
    post:
      operationId: reportPresence
      summary: Report Presence
      description: >-
        Publish the player's online / playing presence. Returns the current
        presence of every online friend.
      tags:
        - Presence
      security:
        - bearerAuth: []
      requestBody:
        required: true
        description: Presence payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PresenceReport'
      responses:
        '200':
          description: Friends' presence snapshot.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PresenceEntry'
        '401':
          description: Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /player/certificates:
    post:
      operationId: getPlayerCertificates
      summary: Get Player Certificates
      description: >-
        Issue an RSA keypair plus Mojang signatures for use in signing the
        player's outbound chat. Keys rotate roughly every 48 hours.
      tags:
        - Keys
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Player keypair and signature material.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerCertificates'
        '401':
          description: Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /publickeys:
    get:
      operationId: getPublicKeys
      summary: Get Mojang Public Keys
      description: >-
        Return the current Mojang public keys used to verify profile property
        signatures, player chat-signing certificates, and authentication
        artefacts.
      tags:
        - Keys
      responses:
        '200':
          description: Public-key bundle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicKeys'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /entitlements/mcstore:
    get:
      operationId: getMinecraftEntitlements
      summary: Get Minecraft Entitlements
      description: >-
        Return the authenticated account's Minecraft store entitlements
        (Minecraft Java, Minecraft Bedrock, character creator items,
        product owner status, etc.).
      tags:
        - Entitlements
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Entitlements list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entitlements'
        '401':
          description: Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    XboxLoginRequest:
      type: object
      description: Body for /authentication/login_with_xbox.
      required:
        - identityToken
      properties:
        identityToken:
          type: string
          description: >-
            XSTS identity token formatted as `XBL3.0 x={userhash};{token}`.
          example: XBL3.0 x=2535465465465465;eyJhbGciOiJSUzI1NiIs...
        ensureLegacyEnabled:
          type: boolean
          description: When true, ensures legacy Mojang accounts can also log in.
          example: true
    MinecraftAccessToken:
      type: object
      description: Successful response from /authentication/login_with_xbox.
      required:
        - access_token
      properties:
        username:
          type: string
          description: Internal Mojang account UUID (different from the player UUID).
          example: 0c11b18a48e94c8d8d8c8f2b3a4e1234
        roles:
          type: array
          description: Account roles array (typically empty for player accounts).
          items:
            type: string
          example: []
        access_token:
          type: string
          description: Minecraft Bearer access token.
          example: eyJraWQiOiJhYmMxMjMi...
        token_type:
          type: string
          description: Token type (always `Bearer`).
          example: Bearer
        expires_in:
          type: integer
          description: Token lifetime in seconds.
          example: 86400
    Profile:
      type: object
      description: A Minecraft player profile (id / name pair).
      required:
        - id
        - name
      properties:
        id:
          type: string
          description: Player UUID without hyphens.
          example: 853c80ef3c3749fdaa49938b674adae6
        name:
          type: string
          description: Current player username.
          example: jeb_
    AuthenticatedProfile:
      type: object
      description: The authenticated player's own profile with skins and capes.
      required:
        - id
        - name
      properties:
        id:
          type: string
          description: Player UUID without hyphens.
          example: 853c80ef3c3749fdaa49938b674adae6
        name:
          type: string
          description: Current username.
          example: jeb_
        skins:
          type: array
          description: All skins owned by the player; one is marked ACTIVE.
          items:
            $ref: '#/components/schemas/Skin'
        capes:
          type: array
          description: All capes owned by the player; one may be marked ACTIVE.
          items:
            $ref: '#/components/schemas/Cape'
        profileActions:
          type: array
          description: Sanctions in effect on the profile (e.g. FORCED_NAME_CHANGE).
          items:
            type: string
          example: []
    Skin:
      type: object
      description: A skin owned by the authenticated player.
      required:
        - id
        - state
        - url
        - variant
      properties:
        id:
          type: string
          description: Skin UUID.
          example: cd9a82a0-0b9c-4f10-8c2a-1b1f87b2af80
        state:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
          example: ACTIVE
        url:
          type: string
          format: uri
          description: Texture URL.
          example: https://textures.minecraft.net/texture/abc123...
        textureKey:
          type: string
          description: Texture content hash.
          example: abc123def456...
        variant:
          type: string
          enum:
            - CLASSIC
            - SLIM
          example: CLASSIC
        alias:
          type: string
          description: Skin alias / nickname.
          example: Steve
    Cape:
      type: object
      description: A cape owned by the authenticated player.
      required:
        - id
        - state
        - url
      properties:
        id:
          type: string
          description: Cape UUID.
          example: 1981aad373fa9754
        state:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
          example: ACTIVE
        url:
          type: string
          format: uri
          description: Cape texture URL.
          example: https://textures.minecraft.net/texture/cape123...
        alias:
          type: string
          description: Cape display name.
          example: Migrator
    NameChangeInfo:
      type: object
      description: Name-change cooldown information.
      properties:
        changedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the most recent name change.
          example: '2025-04-12T18:30:00Z'
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the player profile's creation.
          example: '2014-11-19T12:42:43Z'
        nameChangeAllowed:
          type: boolean
          description: True if a name change is currently allowed.
          example: true
    NameAvailability:
      type: object
      description: Response from the name-availability check.
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - AVAILABLE
            - DUPLICATE
            - NOT_ALLOWED
          example: AVAILABLE
    ChangeSkinRequest:
      type: object
      description: JSON body for the URL-based skin-change call.
      required:
        - variant
        - url
      properties:
        variant:
          type: string
          enum:
            - classic
            - slim
          example: classic
        url:
          type: string
          format: uri
          description: Public URL of the PNG skin image.
          example: https://example.com/skins/my-skin.png
    CapeSelection:
      type: object
      description: Cape-selection payload.
      required:
        - capeId
      properties:
        capeId:
          type: string
          description: UUID of the cape to set active.
          example: 1981aad373fa9754
    PlayerAttributes:
      type: object
      description: Account-level player attributes.
      properties:
        privileges:
          $ref: '#/components/schemas/PrivilegeMap'
        profanityFilterPreferences:
          $ref: '#/components/schemas/ProfanityFilterPreferences'
        friendsPreferences:
          $ref: '#/components/schemas/FriendsPreferences'
        banStatus:
          $ref: '#/components/schemas/BanStatus'
    PlayerAttributesUpdate:
      type: object
      description: Patch payload for updating player attributes.
      properties:
        profanityFilterPreferences:
          $ref: '#/components/schemas/ProfanityFilterPreferences'
        friendsPreferences:
          $ref: '#/components/schemas/FriendsPreferences'
    PrivilegeMap:
      type: object
      description: Flag map of account privileges.
      properties:
        onlineChat:
          type: object
          properties:
            enabled:
              type: boolean
              example: true
        multiplayerServer:
          type: object
          properties:
            enabled:
              type: boolean
              example: true
        multiplayerRealms:
          type: object
          properties:
            enabled:
              type: boolean
              example: true
        telemetry:
          type: object
          properties:
            enabled:
              type: boolean
              example: true
    ProfanityFilterPreferences:
      type: object
      description: Profanity filter settings.
      properties:
        profanityFilterOn:
          type: boolean
          description: Master toggle for the profanity filter on inbound chat.
          example: true
    FriendsPreferences:
      type: object
      description: Friends-graph privacy settings.
      properties:
        allowFriendRequests:
          type: boolean
          description: Whether other players may send friend requests.
          example: true
    BanStatus:
      type: object
      description: Active ban / suspension status, if any.
      properties:
        bannedScopes:
          type: object
          additionalProperties: true
          description: Map of scope -> ban metadata.
    Blocklist:
      type: object
      description: Player privacy blocklist.
      properties:
        blockedProfiles:
          type: array
          description: UUIDs of blocked players.
          items:
            type: string
          example:
            - 853c80ef3c3749fdaa49938b674adae6
    FriendsList:
      type: object
      description: Friends and pending friend requests for the authenticated player.
      properties:
        friends:
          type: array
          description: Confirmed friends.
          items:
            $ref: '#/components/schemas/Friend'
        incomingRequests:
          type: array
          description: Pending inbound friend requests.
          items:
            $ref: '#/components/schemas/Friend'
        outgoingRequests:
          type: array
          description: Pending outbound friend requests.
          items:
            $ref: '#/components/schemas/Friend'
        empty:
          type: boolean
          description: Convenience flag — true if no friends or requests.
          example: false
    Friend:
      type: object
      description: A friend or pending friend.
      required:
        - profile
      properties:
        profile:
          $ref: '#/components/schemas/Profile'
        addedAt:
          type: string
          format: date-time
          description: When the friendship was established.
          example: '2025-04-12T18:30:00Z'
    FriendUpdateRequest:
      type: object
      description: Body for PUT /friends.
      required:
        - updateType
      properties:
        profileName:
          type: string
          description: Friend's username (mutually exclusive with profileId).
          example: Dinnerbone
        profileId:
          type: string
          description: Friend's UUID (mutually exclusive with profileName).
          example: 853c80ef3c3749fdaa49938b674adae6
        updateType:
          type: string
          enum:
            - ADD
            - REMOVE
          example: ADD
    PresenceReport:
      type: object
      description: Body for POST /presence.
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - OFFLINE
            - ONLINE
            - PLAYING_OFFLINE
            - PLAYING_HOSTED_SERVER
            - PLAYING_REALMS
            - PLAYING_SERVER
          example: PLAYING_SERVER
        joinInfo:
          type: object
          additionalProperties: true
          description: Optional server / realm join metadata.
    PresenceEntry:
      type: object
      description: A friend's current presence.
      properties:
        profileId:
          type: string
          description: Friend UUID.
          example: 853c80ef3c3749fdaa49938b674adae6
        status:
          type: string
          enum:
            - OFFLINE
            - ONLINE
            - PLAYING_OFFLINE
            - PLAYING_HOSTED_SERVER
            - PLAYING_REALMS
            - PLAYING_SERVER
          example: PLAYING_SERVER
        lastUpdated:
          type: string
          format: date-time
          example: '2026-05-30T12:00:00Z'
    PlayerCertificates:
      type: object
      description: Player keypair payload returned by /player/certificates.
      properties:
        keyPair:
          type: object
          description: PEM-encoded RSA keypair.
          properties:
            privateKey:
              type: string
              example: -----BEGIN RSA PRIVATE KEY-----...
            publicKey:
              type: string
              example: -----BEGIN RSA PUBLIC KEY-----...
        publicKeySignature:
          type: string
          description: Mojang signature over the public key (legacy).
          example: a1b2c3...
        publicKeySignatureV2:
          type: string
          description: Mojang signature including player UUID (v2).
          example: a1b2c3...
        expiresAt:
          type: string
          format: date-time
          description: Keypair expiry time.
          example: '2026-06-01T00:00:00Z'
        refreshedAfter:
          type: string
          format: date-time
          description: Earliest time the client should re-request the keypair.
          example: '2026-05-31T12:00:00Z'
    PublicKeys:
      type: object
      description: Mojang public keys for verifying signatures.
      properties:
        profilePropertyKeys:
          type: array
          description: Keys used to verify session-profile property signatures.
          items:
            $ref: '#/components/schemas/PublicKeyEntry'
        playerCertificateKeys:
          type: array
          description: Keys used to verify player chat-signature certificates.
          items:
            $ref: '#/components/schemas/PublicKeyEntry'
        authenticationKeys:
          type: array
          description: Keys used to verify Mojang authentication tokens.
          items:
            $ref: '#/components/schemas/PublicKeyEntry'
    PublicKeyEntry:
      type: object
      description: A single Base64-encoded DER public key entry.
      required:
        - publicKey
      properties:
        publicKey:
          type: string
          description: Base64-encoded DER public key.
          example: MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC...
    Entitlements:
      type: object
      description: Account entitlements for Minecraft store items.
      properties:
        items:
          type: array
          description: Owned entitlement items.
          items:
            $ref: '#/components/schemas/EntitlementItem'
        signature:
          type: string
          description: Mojang signature over the items array.
          example: eyJraWQiOiJhYmMxMjMi...
        keyId:
          type: string
          description: Key identifier used for the signature.
          example: 1
    EntitlementItem:
      type: object
      description: A single Minecraft entitlement item.
      required:
        - name
      properties:
        name:
          type: string
          description: Entitlement name (e.g. product_minecraft, game_minecraft).
          example: product_minecraft
        source:
          type: string
          description: How the entitlement was granted (PURCHASE, GIFT, MS_STORE).
          example: PURCHASE
        signature:
          type: string
          description: Mojang signature for this item.
          example: a1b2c3...
    Error:
      type: object
      description: Standard Minecraft Services error envelope.
      properties:
        path:
          type: string
          description: Request path that produced the error.
          example: /minecraft/profile/lookup/name/zzzzzzzzzzzzzz
        errorType:
          type: string
          description: Mojang error class.
          example: NOT_FOUND
        error:
          type: string
          description: Short error name.
          example: NOT_FOUND
        errorMessage:
          type: string
          description: Human-readable description.
          example: Couldn't find any profile with name zzzzzzzzzzzzzz
        developerMessage:
          type: string
          description: Optional developer-facing message.
          example: Couldn't find any profile with name zzzzzzzzzzzzzz
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Minecraft access token issued by /authentication/login_with_xbox.
        Used as `Authorization: Bearer {token}`.
security: []