Skip to main content
The MojangAPI utility provides methods for interacting with the Mojang API to fetch player information, profiles, and manage skins.

​
Accessing MojangAPI

Get an instance using dependency injection: 
import gg.essential.api.utils.mojang.MojangAPI
import gg.essential.api.utils.get

val mojangAPI = get<MojangAPI>()

​
Player lookups

​
getUUID

Get a player’s UUID from their username. 
import java.util.UUID

val future = mojangAPI.getUUID("Notch")
future?.thenAccept { uuid ->
    println("UUID: $uuid")
}

​
getName

Get a player’s current username from their UUID. 
import java.util.UUID

val uuid = UUID.fromString("069a79f4-44e9-4726-a5be-fca90e38aaf5")
val future = mojangAPI.getName(uuid)
future?.thenAccept { name ->
    println("Username: $name")
}

​
Profile data

​
getProfile

Get a complete player profile including skin and cape information. 
import gg.essential.api.utils.mojang.Profile
import java.util.UUID

val uuid = UUID.fromString("069a79f4-44e9-4726-a5be-fca90e38aaf5")
val profile = mojangAPI.getProfile(uuid)

if (profile != null) {
    println("Name: ${profile.name}")
    println("ID: ${profile.id}")
    
    // Access textures
    val textures = profile.textures
    val skinUrl = textures.textures?.skin?.url
    val capeUrl = textures.textures?.cape?.url
    
    println("Skin: $skinUrl")
    if (capeUrl != null) {
        println("Cape: $capeUrl")
    }
}

​
Skin management

​
changeSkin

Change a player’s skin using their session token. 
import gg.essential.api.utils.mojang.Model
import gg.essential.api.utils.mojang.SkinResponse
import java.util.UUID

val accessToken = "player_session_token"
val uuid = UUID.fromString("069a79f4-44e9-4726-a5be-fca90e38aaf5")
val skinUrl = "https://example.com/skin.png"

val response = mojangAPI.changeSkin(
    accessToken,
    uuid,
    Model.STEVE,
    skinUrl
)

if (response != null) {
    println("Skin changed successfully!")
    println("Response: ${response.id}")
}
After successfully changing a skin, the player must disconnect from their current server and reconnect to see the changes.

​
Data types

​
Profile

Player profile data from the Mojang API.
​
id
String?
Player UUID as a string without dashes.
​
name
String?
Player’s current username.
​
properties
List<Property>?
Profile properties containing encoded texture data.
​
textures
ProfileTextures
Decoded skin and cape information (computed property).

​
ProfileTextures

Decoded texture information for a player.
​
timestamp
Long?
Timestamp of when the profile was fetched.
​
profileId
String?
Player’s UUID.
​
profileName
String?
Player’s username.
​
textures
Textures?
Skin and cape texture URLs.

​
Textures

Skin and cape texture URLs.
​
skin
TextureURL?
Player’s skin texture.
​
cape
TextureURL?
Player’s cape texture (if they have one).

​
Model

Skin model type enumeration.
​
STEVE
Model
Classic/default skin model with 4-pixel wide arms.
​
ALEX
Model
Slim skin model with 3-pixel wide arms.

​
Model methods

// Get model by internal type
val model = Model.byType("slim") // ALEX

// Get model by variant (Mojang API name)
val model2 = Model.byVariant("classic") // STEVE

// With default fallback
val model3 = Model.byTypeOrDefault("unknown") // STEVE
val model4 = Model.byVariantOrDefault("invalid") // STEVE

​
SkinResponse

Response from a skin change request.
​
id
String
Response identifier.
​
name
String
Player’s username.
​
skins
List<Skin>?
List of player’s skins.
​
capes
List<Skin>
List of player’s capes.

​
API reference

​
Methods

​
getUUID
(name: String) -> CompletableFuture<UUID>?
Get a player’s UUID from their username. Returns null if the request fails.See wiki.vg documentation.
​
getName
(uuid: UUID) -> CompletableFuture<String>?
Get a player’s username from their UUID. Returns null if the request fails.See wiki.vg documentation.
​
getProfile
(uuid: UUID) -> Profile?
Get the complete player profile including skin and cape data. Returns null if the request fails.See wiki.vg documentation.
​
changeSkin
(accessToken: String, uuid: UUID, model: Model, url: String) -> SkinResponse?
Send a skin change request. Requires a valid session token for authentication. Returns null if the request fails.See wiki.vg documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us