Difference between revisions of "Mojang API"
(→Payload: prepaid_card_redeemed_cobalt also exists, with a total of... 1.) |
m (Mention full Golang API wrapper) |
||
Line 516: | Line 516: | ||
[https://github.com/hawezo/MojangSharp C#] | full API wrapper | [https://github.com/hawezo/MojangSharp C#] | full API wrapper | ||
+ | |||
+ | [https://github.com/Lukaesebrot/mojango Go] | full API wrapper | ||
[https://github.com/PhilipBorgesen/minecraft/tree/master/profile Go] | UUIDs or names to profiles with skins, capes and name histories | [https://github.com/PhilipBorgesen/minecraft/tree/master/profile Go] | UUIDs or names to profiles with skins, capes and name histories |
Revision as of 23:31, 24 May 2020
Contents
Notes
- All public APIs are rate limited so you are expected to cache the results. This is currently set at 600 requests per 10 minutes but this may change.
- For some parts of the API, demo accounts are sometimes included, sometimes not. Mojang keeps changing this.
API Status
GET https://status.mojang.com/check
Returns status of various Mojang services. Possible values are green
(no issues), yellow
(some issues), red
(service unavailable).
Response
[
{
"minecraft.net": "yellow"
},
{
"session.minecraft.net": "green"
},
{
"account.mojang.com": "green"
},
{
"auth.mojang.com": "green"
},
{
"skins.minecraft.net": "green"
},
{
"authserver.mojang.com": "green"
},
{
"sessionserver.mojang.com": "yellow"
},
{
"api.mojang.com": "green"
},
{
"textures.minecraft.net": "red"
},
{
"mojang.com": "green"
}
]
Username -> UUID at time
GET https://api.mojang.com/users/profiles/minecraft/<username>?at=<timestamp>
This will return the UUID of the name at the timestamp provided.
?at=0
can be used to get the UUID of the original user of that username, however, it only works if the name was changed at least once, or if the account is legacy.
- The timestamp is a UNIX timestamp (without milliseconds)
- When the
at
parameter is not sent, the current time is used
Response
{
"id": "7125ba8b1c864508b92bb5c042ccfe2b",
"name": "KrisJelbring"
}
name
is the current name of that uuid, it is not the name requested!legacy
only appears when true (not migrated to mojang account)demo
only appears when true (account unpaid)
If there is no player with the given username an HTTP status code 204 (No Content) is sent without any HTTP body.
If the timestamp is not a number, too big or too small the HTTP status code 400 (Bad Request) is sent with an error message looking like this:
{
"error": "IllegalArgumentException",
"errorMessage": "Invalid timestamp."
}
UUID -> Name history
GET https://api.mojang.com/user/profiles/<uuid>/names
Returns all the usernames this user has used in the past and the one they are using currently. The UUID must be given without hyphens.
Response
[
{
"name": "Gold"
},
{
"name": "Diamond",
"changedToAt": 1414059749000
}
]
The changedToAt
field is a Java timestamp in milliseconds.
Playernames -> UUIDs
POST https://api.mojang.com/profiles/minecraft
This will return player UUIDs and some extras.
Payload
[
"maksimkurb",
"nonExistingPlayer" //Test for non-existing player
]
Response
[
{
"id": "0d252b7218b648bfb86c2ae476954d32",
"name": "maksimkurb",
"legacy": true,
"demo": true
}
]
- name is case-corrected
- legacy only appears when true (profile not migrated to mojang.com)
- demo only appears when true (account unpaid)
- IllegalArgumentException is returned when any of the usernames is null or ""
- The
Content-Type
HTTP header must beapplication/json
- You cannot request more than 10 names per request
UUID -> Profile + Skin/Cape
GET https://sessionserver.mojang.com/session/minecraft/profile/<uuid>
This will return the player's username plus any additional information about them (e.g. skins). Example: https://sessionserver.mojang.com/session/minecraft/profile/4566e69fc90748ee8d71d7ba5aa00d20
This has a much stricter rate limit: You can request the same profile once per minute, however you can send as many unique requests as you like.
Response
{
"id": "<profile identifier>",
"name": "<player name>",
"properties": [
{
"name": "textures",
"value": "<base64 string>",
"signature": "<base64 string; signed data using Yggdrasil's private key>" // Only provided if ?unsigned=false is appended to url
}
]
}
"legacy": true
will appear in the response if the user has not migrated their minecraft.net account to mojang.
The "value" base64 string for the "textures" object decoded:
{
"timestamp": <java time in ms>,
"profileId": "<profile uuid>",
"profileName": "<player name>",
"signatureRequired": true, // Only present if ?unsigned=false is appended to url
"textures": {
"SKIN": {
"url": "<player skin URL>"
},
"CAPE": {
"url": "<player cape URL>"
}
}
}
- The timestamp is sometimes in the past (probably due to cached results?)
- The
"SKIN"
object will have"metadata": {"model": "slim"}
if the player model has slim arms (“Alex?” style). For square arms (“Steve?” style),"metadata"
will be missing. - If no custom skin has been set,
"SKIN"
will be missing.
Whether the player has the “Alex?” or “Steve?” skin depends on the Java hashCode of their UUID. Steve is used for even hashes. Example implementations:- PHP
- Go
- JavaScript (includes explanation)
- Java (includes sample UUIDs)
- Likewise
"CAPE"
will be missing if the account has no cape.
Change Skin
POST https://api.mojang.com/user/profile/<uuid>/skin
This will set the skin for the selected profile, but Mojang's servers will fetch the skin from a URL. This will also work for legacy accounts.
Response
Upon error the server will send back a JSON with the error. (Success is a blank payload)
Headers
Authorization: Bearer <access token>
Payload
The payload for this API consists of two url-encoded form fields (conjoined by '&').
model=<""/"slim">&url=<skin url>
model is an empty string for the default model and "slim" for the slim model
Example
curl -H "Authorization: Bearer <access token>" --data-urlencode "model=" --data-urlencode "url=http://assets.mojang.com/SkinTemplates/steve.png" https://api.mojang.com/user/profile/<uuid>/skin
POST /user/profile/<uuid>/skin HTTP/1.1 Host: api.mojang.com User-Agent: curl/7.49.0 Accept: */* Authorization: Bearer <access token> Content-Length: 69 Content-Type: application/x-www-form-urlencoded model=&url=http%3A%2F%2Fassets.mojang.com%2FSkinTemplates%2Fsteve.png
Upload Skin
PUT https://api.mojang.com/user/profile/<uuid>/skin
This uploads a skin to Mojang's servers. It also sets the users skin. This works on legacy counts as well.
Response
No response unless error
Headers
Authorization: Bearer <access token>
Payload
The payload for this API consists of multipart form data. There are two parts (order does not matter b/c of boundary):
model | Empty string for the default model and "slim" for the slim model |
file | Raw image file data |
Example
curl -X PUT -H "Authorization: Bearer <access token>" -F model=alex -F file="@alex.png;type=image/png" https://api.mojang.com/user/profile/<uuid>/skin
PUT /user/profile/<uuid>/skin HTTP/1.1 Host: api.mojang.com User-Agent: curl/7.49.0 Accept: */* Authorization: Bearer <access token> Content-Length: <length> Content-Type: multipart/form-data; boundary=<boundary> --<boundary> Content-Disposition: form-data; name="model" slim --<boundary> Content-Disposition: form-data; name="file"; filename="alex.png" Content-Type: image/png <image data> --<boundary>--
Reset Skin
DELETE https://api.mojang.com/user/profile/<uuid>/skin
Resets the user's skin to the default one.
Response
No response unless error
Headers
Authorization: Bearer <access token>
Example
curl -X DELETE -H "Authorization: Bearer <access token>" https://api.mojang.com/user/profile/<uuid>/skin
DELETE /user/profile/<uuid>/skin HTTP/1.1 Host: api.mojang.com User-Agent: curl/7.46.0 Accept: */* Authorization: Bearer <access token>
Security question-answer flow
This is required to get the skin change endpoint to work in case the services do not trust your IP yet.
Check if security questions are needed
GET https://api.mojang.com/user/security/location Authorization: Bearer <access token>
Good answer:
204 NO CONTENT
Bad answer:
{
"error": "ForbiddenOperationException",
"errorMessage": "Current IP is not secured"
}
Get list of questions
GET https://api.mojang.com/user/security/challenges Authorization: Bearer <access token>
Answer:
[
{
"answer": {
"id": 123
},
"question": {
"id": 1,
"question": "What is your favorite pet's name?"
}
},
{
"answer": {
"id": 456
},
"question": {
"id": 2,
"question": "What is your favorite movie?"
}
},
{
"answer": {
"id": 789
},
"question": {
"id": 3,
"question": "What is your favorite author's last name?"
}
}
],
The possible IDs are these:
1 What is your favorite pet's name? 2 What is your favorite movie? 3 What is your favorite author's last name? 4 What is your favorite artist's last name? 5 What is your favorite actor's last name? 6 What is your favorite activity? 7 What is your favorite restaurant? 8 What is the name of your favorite cartoon? 9 What is the name of the first school you attended? 10 What is the last name of your favorite teacher? 11 What is your best friend's first name? 12 What is your favorite cousin's name? 13 What was the first name of your first girl/boyfriend? 14 What was the name of your first stuffed animal? 15 What is your mother's middle name? 16 What is your father's middle name? 17 What is your oldest sibling's middle name? 18 In what city did your parents meet? 19 In what hospital were you born? 20 What is your favorite team? 21 How old were you when you got your first computer? 22 How old were you when you got your first gaming console? 23 What was your first video game? 24 What is your favorite card game? 25 What is your favorite board game? 26 What was your first gaming console? 27 What was the first book you ever read? 28 Where did you go on your first holiday? 29 In what city does your grandmother live? 30 In what city does your grandfather live? 31 What is your grandmother's first name? 32 What is your grandfather's first name? 33 What is your least favorite food? 34 What is your favorite ice cream flavor? 35 What is your favorite ice cream flavor? 36 What is your favorite place to visit? 37 What is your dream job? 38 What color was your first pet? 39 What is your lucky number?
Send back the answers
POST https://api.mojang.com/user/security/location Authorization: Bearer <access token>
[
{
"id": 123,
"answer" : "foo"
},
{
"id": 456,
"answer" : "bar"
},
{
"id": 589,
"answer" : "baz"
}
]
On failure, you will get some sort of error. Unless it's a syntax or json structure error, it will be this:
{
"error": "ForbiddenOperationException",
"errorMessage": "At least one answer was incorrect"
}
On success:
204 NO CONTENT
Blocked Servers
GET https://sessionserver.mojang.com/blockedservers
Returns a list of SHA1 hashes used to check server addresses against when the client tries to connect.
Clients check the lowercase name, using the ISO-8859-1 charset, against this list. They will also attempt to check subdomains, replacing each level with a *
. Specifically, it splits based off of the .
in the domain, goes through each section removing one at a time. For instance, for mc.example.com
, it would try mc.example.com
, *.example.com
, and *.com
. With IP addresses (verified by having 4 split sections, with each section being a valid integer between 0 and 255, inclusive) substitution starts from the end, so for 192.168.0.1
, it would try 192.168.0.1
, 192.168.0.*
, 192.168.*
, and 192.*
.
This check is done by the bootstrap class in netty. The default netty class is overridden by one in the com.mojang:netty dependency loaded by the launcher. This allows it to affect any version that used netty (1.7+)
Response
A line separated list of all SHA1 hashes.
Some of the current ~2200 hashes have been cracked.
6f2520f8bd70a718c568ab5274c56bdbbfc14ef4:*.minetime.com 7ea72de5f8e70a2ac45f1aa17d43f0ca3cddeedd:*.trollingbrandon.club c005ad34245a8f2105658da2d6d6e8545ef0f0de:*.skygod.us c645d6c6430db3069abd291ec13afebdb320714b:*.mineaqua.es 8bf58811e6ebca16a01b842ff0c012db1171d7d6:*.eulablows.host 8789800277882d1989d384e7941b6ad3dadab430:*.moredotsmoredots.xyz e40c3456fb05687b8eeb17213a47b263d566f179:*.brandonlovescock.bid 278b24ffff7f9f46cf71212a4c0948d07fb3bc35:*.brandonlovescock.club c78697e385bfa58d6bd2a013f543cdfbdc297c4f:*.mineaqua.net b13009db1e2fbe05465716f67c8d58b9c0503520:*.endercraft.com 3e560742576af9413fca72e70f75d7ddc9416020:*.insanefactions.org 986204c70d368d50ffead9031e86f2b9e70bb6d0:*.playmc.mx 65ca8860fa8141da805106c0389de9d7c17e39bf:*.howdoiblacklistsrv.host 7dca807cc9484b1eed109c003831faf189b6c8bf:*.brandonlovescock.online c6a2203285fb0a475c1cd6ff72527209cc0ccc6e:*.brandonlovescock.press e3985eb936d66c9b07aa72c15358f92965b1194e:*.insanenetwork.org b140bec2347bfbe6dcae44aa876b9ba5fe66505b:*.phoenixnexus.net 27ae74becc8cd701b19f25d347faa71084f69acd:*.arkhamnetwork.org 48f04e89d20b15de115503f22fedfe2cb2d1ab12:brandonisan.unusualperson.com 9f0f30820cebb01f6c81f0fdafefa0142660d688:*.kidslovemy500dollarranks.club cc90e7b39112a48064f430d3a08bbd78a226d670:*.eccgamers.com 88f155cf583c930ffed0e3e69ebc3a186ea8cbb7:*.fucktheeula.com 605e6296b8dba9f0e4b8e43269fe5d053b5f4f1b:*.mojangendorsesbrazzers.webcam 5d2e23d164a43fbfc4e6093074567f39b504ab51:touchmybody.redirectme.net f3df314d1f816a8c2185cd7d4bcd73bbcffc4ed8:*.mojangsentamonkeyinto.space 073ca448ef3d311218d7bd32d6307243ce22e7d0:*.diacraft.org 33839f4006d6044a3a6675c593fada6a690bb64d:*.diacraft.de e2e12f3b7b85eab81c0ee5d2e9e188df583fe281:*.eulablacklist.club 11a2c115510bfa6cb56bbd18a7259a4420498fd5:*.slaughterhousepvp.com 75df09492c6c979e2db41116100093bb791b8433:*.timelesspvp.net d42339c120bc10a393a0b1d2c6a2e0ed4dbdd61b:*.herowars.org 4a1b3b860ba0b441fa722bbcba97a614f6af9bb8:justgiveinandblockddnsbitches.ddns.net b8c876f599dcf5162911bba2d543ccbd23d18ae5:brandonisagainst.health-carereform.com 9a9ae8e9d0b6f3bf54c266dcd1e4ec034e13f714:brandonwatchesporn.onthewifi.com 336e718ffbc705e76b4a72884172c6b95216b57c:canyouwildcardipsplease.gotdns.ch 27cf97ecf24c92f1fe5c84c5ff654728c3ee37dd:letsplaysome.servecounterstrike.com 32066aa0c7dc9b097eed5b00c5629ad03f250a2d:mojangbrokeintomy.homesecuritymac.com 39f4bbfd123a5a5ddbf97489877831c15a70d7f2:*.primemc.org f32f824d41aaed334aef248fbe3a0f8ecf4ac1a0:*.meep.in c22efe4cf7fb319ca2387bbc930c1fdf77ab72fc:*.itsjerryandharry.com cc8e1ae93571d144bf4b37369cb8466093d6db5a:*.thearchon.net 9c0806e5ffaccb45121e57e4ce88c7bc76e057f1:*.goatpvp.com 5ca81746337088b7617c851a1376e4f00d921d9e:*.gotpvp.com a5944b9707fdb2cc95ed4ef188cf5f3151ac0525:*.guildcraft.org
Statistics
POST https://api.mojang.com/orders/statistics
Get statistics on the sales of Minecraft.
Payload
The payload is a json list of options under the metricKeys key. You will receive a single object corresponding to the sum of sales of the requested type(s). You must request at least one type of sale. Below is the default list used by https://minecraft.net/en/stats/
{
"metricKeys": [
"item_sold_minecraft",
"prepaid_card_redeemed_minecraft"
]
}
Valid options are:
item_sold_minecraft prepaid_card_redeemed_minecraft item_sold_cobalt item_sold_scrolls prepaid_card_redeemed_cobalt item_sold_dungeons
Response
A json object is returned with the total amount of copies sold, the amount of copies sold in the last 24h and how many sales there are per second.
{
"total": integer total amount sold,
"last24h": integer total sold in last 24 hours,
"saleVelocityPerSeconds": decimal average sales per second
}
Examples
C# | full API wrapper
Go | full API wrapper
Go | UUIDs or names to profiles with skins, capes and name histories
Python | full API wrapper
Python | UUIDs or names to profiles
Python | names file to uuids+names file
PHP | UUIDs or names to profiles with skins, heads and name histories
PHP | UUIDs to names
PHP | UUIDs to names, names to uuids
Java | Almost full API Wrapper
JavaScript | UUIDs or names to profiles with skins, capes and name histories