Minecraft Verification API Docs

The Minecraft Verification API is intended to give developers the ability to expand their existing verification services, or to build MC Verification data into existing services. Here are some examples:

• Automatically detect a user's Minecraft account for ingame-data based commands
• Adding Minecraft support to an existing verification system
• Extending the verified user's in an existing Minecraft Verification system
• Ease transfering from a previous verification system

There are many more examples, and there are few limits to the potential useage opportunities given they fall within API restrictions.

API Tokens & Limits

An API token is a private UUID linked to your Discord ID which is required to interface with the API. API tokens must be kept confidential and not shared with other users. The !api generate command can be DMed to the bot to get an API key, if you forget your API key, you can recover it and see other related info with !api info. If your API key is leaked (such as via Git), use !api regenerate to get a new one.

By default, every token is limited to 100 requests/min, though this limit may change in future (if it does you will be notified). You should never use multiple tokens to bypass this limit, if you need an increased limit, or you have been banned, contact ChimneySwift#1337 via DM (Join the official Minecraft Discord, or Skyblock Community) or email management@skyblock.community and explain why you need an increased limit (or why you were banned and why you should be unbanned). If you email, be sure to include your Discord user ID in the email.

You should always monitor your requests/min and cache responses within your own projects to avoid exceeding the limit, if you're rate limited or banned due to excessive requests, you will be DMed by the bot. Exceeding the rate limit will increase your "strikes", if you reach three strikes your token is banned and you will need to request for it to be unbanned.

Note: Errors count as requests.

Reasons for being banned include:

• API spam/abuse (same request too quickly, too many errors, etc)
• Exceeding the API limit three times
• Leaking your token
• Using multiple tokens
• Trying to circumvent a ban using an alt

Our API is fairly forgiving, this also extends to unbanning users. If you've been banned or stiked due to a bug in your code, a surprise influx in usage, etc, you won't permanently lose access. Just contact us and give us a detailed explaination as to your issue. TL;DR: Respect the API and we'll be sure to support you in turn.

API Methods

There are several API methods available, all of which use the following service endpoint:

https://skyblock.community/api

The methods (listed below) all require an Authorization header, with the value being your API token.

See below for detailed request examples and responses

General Notes

Most API responses return timestamps, the format for these is always YYYY-MM-DDTHH:MM:SS.sss.

Minecraft UUIDs are always sent and expected to be recieved as "dashless", ie with all - stripped out.

All JSON response bodies will have a top level data value with key status, which is the HTTP status code returned for the response. Successful requests will always have a status of 200.

Token Info

This method returns a JSON object containing various info relating to the used token. It's recommended to use this request to validate your token isn't banned, and to dynamically load your token's current rate limit.

HTTP Request

GET https://skyblock.community/api/token_info

Response Body

The method will return the following JSON response, or an error:

{
    "status": 200,
    "owner_id": 371478031996420099,
    "rate_limit": 100,
    "strikes": 0,
    "total_requests": 11246,
    "banned": false,
    "creation_date": "2021-01-06T08:32:48.969",
    "requests_last_min": 20
}

Example Code

Python example using the requests module:

import requests

HEADERS = {'Authorization': 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'} # Replace this with your token

resp = requests.get("https://skyblock.community/api/token_info", headers=headers)

data = resp.json()

print(data)

Discord

This method returns the verification info given a single Minecraft UUID.

HTTP Request

POST https://skyblock.community/api/discord

Request Body

This method requires a JSON dictionary as shown below with sample data:

{
    "uuid": "387f08493809421083335d781a508640"
}

IMPORTANT: UUID must be "dashless", meaning all - are stripped. This is the same format the Mojang API uses. A request of a user ID with length different to 32 characters will return an error.

Usernames will also not work, you'll need to convert them to UUIDs using the Mojang API

Response Body

The method will return the following JSON response, or an error:

{
    "status": 200,
    "user_id": 371478031996420099,
    "verified_guild": 651641640133591071,
    "verified_time": "2021-01-11T10:15:49.071"
}

Example Code

Python example using the requests module:

import requests

HEADERS = {'Authorization': 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'} # Replace this with your token

payload = {
    "uuid": "387f08493809421083335d781a508640",
}

resp = requests.post("https://skyblock.community/api/discord", json=payload, headers=headers)

data = resp.json()

print(data)

Minecraft

This method returns the verification info given a single Discord ID.

HTTP Request

POST https://skyblock.community/api/minecraft

Request Body

This method requires a JSON dictionary as shown below with sample data:

{
    "user_id": 371478031996420099
}

Response Body

The method will return the following JSON response, or an error:

{
    "status": 200,
    "uuid": "387f08493809421083335d781a508640",
    "verified_guild": 651641640133591071,
    "verified_time": "2021-01-11T10:15:49.071"
}

Example Code

Python example using the requests module:

import requests

HEADERS = {'Authorization': 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'} # Replace this with your token

payload = {
    "user_id": 371478031996420099,
}

resp = requests.post("https://skyblock.community/api/minecraft", json=payload, headers=headers)

data = resp.json()

print(data)

Bulk Discord

This method returns verification data for up to 20 users at once. It is prefered that the individual response method is used when only one user needs to be requested.

HTTP Request

POST https://skyblock.community/api/bulk/discord

Request Body

This method requires a JSON dictionary as shown below with sample data:

{
    "users": [
        "387f08493809421083335d781a508640",
        "f7c77d999f154a66a87dc4a51ef30d19",
        "b2732392fae140c3b836a066c6debd8f",
        "b876ec32e396476ba1158438d83c67d4",
        ...
        "1e18d5ff643d45c8b50943b8461d8614"
    ]
}

Up to 20 users can be requested at once. Duplicate entries will still be considered in the limit, but they will only be placed in the response body once.

IMPORTANT: UUIDs must be "dashless", meaning all - are stripped. This is the same format the Mojang API uses. A request of a user ID with length different to 32 characters will return an error.

Usernames will also not work, you'll need to convert them to UUIDs using the Mojang API

Response Body

The method will return the following JSON response, or an error:

{
    "status": 200,
    "count": 3,
    "users": [{
        "user_id": 371478031996420099,
        "verified_guild": 651641640133591071,
        "verified_time": "2021-01-11T10:15:49.071",
        "uuid": "387f08493809421083335d781a508640"
    }, {
        "error": "Not Found",
        "message": "The requested user is not verified.",
        "uuid": "b876ec32e396476ba1158438d83c67d4"
    },

        ...

    {
        "error": "Bad Request",
        "message": "Your Discord ID/Minecraft UUID is invalid.",
        "uuid": "bad uuid"
    }]
}

Status doesn't factor if some of the lookups failed, count includes errors. Each entry in users represents one user. The response is identical to the single request, except the uuid field is included.

Example Code

Python example using the requests module:

import requests

HEADERS = {'Authorization': 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'} # Replace this with your token

payload = {
    "users": [
        "387f08493809421083335d781a508640",
        "bad uuid",
        "b876ec32e396476ba1158438d83c67d4"
    ]
}

resp = requests.post("https://skyblock.community/api/bulk/discord", json=payload, headers=headers)

data = resp.json()

print(data)

Bulk Minecraft

This method returns verification data for up to 20 users at once. It is prefered that the individual response method is used when only one user needs to be requested.

HTTP Request

POST https://skyblock.community/api/bulk/minecraft

Request Body

This method requires a JSON dictionary as shown below with sample data:

{
    "users": [
        371478031996420099,
        165811640065982464,
        ...
        294470646425976843
    ]
}

Up to 20 users can be requested at once. Duplicate entries will still be considered in the limit, but they will only be placed in the response body once.

Response Body

The method will return the following JSON response, or an error:

{
    "status": 200,
    "count": 3,
    "users": [{
        "error": "Not Found",
        "message": "The requested user is not verified.",
        "user_id": 165811640065982464
    }, {
        "error": "Bad Request",
        "message": "Your Discord ID/Minecraft UUID is invalid.",
        "user_id": 1234
    },

        ...

    {
        "uuid": "387f08493809421083335d781a508640",
        "verified_guild": 651641640133591071,
        "verified_time": "2021-01-11T10:15:49.071",
        "user_id": 371478031996420099
    }]
}

Status doesn't factor if some of the lookups failed, count includes errors. Each entry in users represents one user. The response is identical to the single request, except the user_id field is included.

Example Code

Python example using the requests module:

import requests

HEADERS = {'Authorization': 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'} # Replace this with your token

payload = {
    "users": [
        371478031996420099,
        165811640065982464,
        1234
    ]
}

resp = requests.post("https://skyblock.community/api/bulk/minecraft", json=payload, headers=headers)

data = resp.json()

print(data)

Error Responses

While there are cases where the API may respond with invalid json, the majority of errors are handled via JSON error responses, separated by HTTP error code below.

400

HTTP 400 is thrown for responses where the user has sent a authorized, but invalid or malformed request. For bulk requests, some of these errors (minus the status field) will replace results.

Malformed/Incorrect Request Body

Response:

{
    "status":400,
    "error":"Bad Request",
    "message":"Your request is not valid JSON."
}

Invalid Discord ID or Minecraft UUID

This error is only thrown if IDs are of invalid length, if they are the correct length a 404 will be thrown instead. Response:

{
    "status":400,
    "error":"Bad Request",
    "message":"Your Discord ID/Minecraft UUID is invalid."
}

Too Many Users Requested

If over 20 users are requested for bulk methods. If less than one are requested, the request malformed error is thrown. Response:

{
    "status":400,
    "error":"Bad Request",
    "message":"Too many users."
}

401

HTTP 401 is thrown when the server is unable to confirm your token. Only one error falls under this category:

{
    "status":401,
    "error":"Unauthorized",
    "message":"Your token is missing or invalid."
}

403

HTTP 403 is thrown when you've been banned or rate limited

Banned

Response:

{
    "status":403,
    "error":"Forbidden",
    "message":"Your token has been banned."
}

Rate Limited

Response:

{
    "status":403,
    "error":"Forbidden",
    "message":"You have been rate limited."
}

404

HTTP 404 is thrown when a user isn't verified in our database.

{
    "status":404,
    "error":"Not Found",
    "message":"The requested user is not verified."
}

500

HTTP 500 is thrown when an internal server error occured. You may not always get a json response with this error code.

High Traffic

Response:

{
    "status":500,
    "error":"Internal Server Error",
    "message":"We are currently experiencing high traffic, please try again later."
}

Further Info

This bot is developed as part of the Skyblock Community Development Project. The lead developer and host for this project is ChimneySwift#1337. If you have questions, concerns, comments or feedback, don't hesitate to contact him directly either via DM (Join the official Minecraft Discord, or Skyblock Community) or email management@skyblock.community.

If this bot helped improve your service or Discord server, please consider helping me cover hosting costs by donating.

MC Verify is in no way affiliated with Minecraft or Mojang AB