OpenAPI Specification
openapi: 3.0.3
info:
title: Minecraft Services Attributes Identity 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: Identity
description: Player UUID and username lookup
paths:
/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
/users/profiles/minecraft/{username}:
get:
operationId: getProfileByUsername
summary: Get Profile by Username
description: Look up a Minecraft player's UUID and profile metadata by their case-insensitive username. Returns 204 / 404 when the username is not currently in use by any account.
tags:
- Identity
parameters:
- name: username
in: path
required: true
description: Case-insensitive Minecraft username.
example: jeb_
schema:
type: string
responses:
'200':
description: Profile found.
content:
application/json:
schema:
$ref: '#/components/schemas/Profile_2'
'204':
description: No profile matched the requested username.
'400':
description: Invalid username supplied.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_2'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_2'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/profiles/minecraft:
post:
operationId: getProfilesByUsernamesBulk
summary: Get Profiles by Usernames (Bulk)
description: Resolve a list of up to ten Minecraft usernames to their profiles in a single request. Names with no matching account are omitted from the response array.
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 for the supplied usernames.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Profile_2'
'400':
description: Empty array or more than ten usernames supplied.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_2'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_2'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
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_
Profile_2:
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 (case-preserving).
example: jeb_
legacy:
type: boolean
description: True if the account has not yet been migrated to Mojang.
example: false
demo:
type: boolean
description: True if the account is a free demo account.
example: false
Error_2:
type: object
description: Standard Mojang error envelope.
properties:
error:
type: string
description: Error class name.
example: IllegalArgumentException
errorMessage:
type: string
description: Human-readable error description.
example: Path /users/profiles/minecraft/ is invalid.
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}`.'