OpenAPI Specification
openapi: 3.0.3
info:
title: Minecraft Services Attributes Session 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)
security: []
tags:
- name: Session
description: Login-handshake session verification
paths:
/session/minecraft/hasJoined:
get:
operationId: hasJoined
summary: Has Joined Verification (Server-Side)
description: Called by a Minecraft server during the login handshake to verify that the client claiming to be `username` has authenticated against Mojang for the supplied `serverId` (a SHA-1 hash of the server's shared secret and public key). Returns the player's full session profile on success.
tags:
- Session
parameters:
- name: username
in: query
required: true
description: Username sent by the connecting client.
example: jeb_
schema:
type: string
- name: serverId
in: query
required: true
description: SHA-1 server hash computed during the handshake.
example: e6e0fce6f3a8b7afa3b9eb0a0d3a8e9a4e8c8e1b
schema:
type: string
- name: ip
in: query
required: false
description: Optional IP of the connecting client for stricter checks.
example: 203.0.113.42
schema:
type: string
- name: prevent_proxy
in: query
required: false
description: When true, fails verification if the client appears proxied.
example: false
schema:
type: boolean
responses:
'200':
description: Player authenticated; returns the session profile.
content:
application/json:
schema:
$ref: '#/components/schemas/SessionProfile'
'204':
description: Verification failed.
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/session/minecraft/join:
post:
operationId: joinSession
summary: Join Session (Client-Side)
description: Called by the Minecraft client during the login handshake to register the session with Mojang before the server's hasJoined check. The request body carries the player's Minecraft access token, profile UUID, and the SHA-1 server hash.
tags:
- Session
requestBody:
required: true
description: Join-session payload.
content:
application/json:
schema:
$ref: '#/components/schemas/JoinRequest'
responses:
'204':
description: Join successful.
'400':
description: Invalid request body.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Access token invalid or revoked.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded (6 joins per 30 seconds per account).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
SessionProfile:
type: object
description: A signed session profile with textures and metadata properties.
required:
- id
- name
- properties
properties:
id:
type: string
description: Player UUID without hyphens.
example: 853c80ef3c3749fdaa49938b674adae6
name:
type: string
description: Player username.
example: jeb_
properties:
type: array
description: Signed property list (currently only `textures`).
items:
$ref: '#/components/schemas/SessionProperty'
profileActions:
type: array
description: Sanctions or actions Mojang has taken on the profile.
items:
type: string
example: FORCED_NAME_CHANGE
SessionProperty:
type: object
description: A single signed session-profile property (e.g. textures).
required:
- name
- value
properties:
name:
type: string
description: Property name (typically `textures`).
example: textures
value:
type: string
description: Base64-encoded JSON payload (skin / cape URLs and metadata).
example: ewogICJ0aW1lc3RhbXAiIDogMTcwMDAwMDAwMDAwMCwKICAicHJvZmlsZUlkIiA6IC4uLgp9
signature:
type: string
description: Mojang RSA signature of `value`. Present only when the request included `unsigned=false`.
example: a1b2c3d4...==
JoinRequest:
type: object
description: Body of the client-side /join call.
required:
- accessToken
- selectedProfile
- serverId
properties:
accessToken:
type: string
description: Minecraft Bearer access token for the player.
example: eyJraWQiOiJhYmMxMjMi...
selectedProfile:
type: string
description: Player UUID without hyphens.
example: 853c80ef3c3749fdaa49938b674adae6
serverId:
type: string
description: SHA-1 hash computed by the client during the handshake.
example: e6e0fce6f3a8b7afa3b9eb0a0d3a8e9a4e8c8e1b
Error:
type: object
description: Standard Mojang error envelope.
properties:
error:
type: string
description: Error class name.
example: ForbiddenOperationException
errorMessage:
type: string
description: Human-readable error description.
example: Invalid token.
cause:
type: string
description: Optional cause classification.
example: UserMigratedException
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'Minecraft access token issued by /authentication/login_with_xbox. Used as `Authorization: Bearer {token}`.'