MinecraftAuth.me

API documentation

Contents: Errors and versioning

Errors and versioning

Errors#

Every error has a matching HTTP status and this body:

{ "error": "No identity is linked to that Minecraft account", "status": 404 }

The error text is meant for logs and people. Branch on status, not on the text.

Status Meaning
400 the request is malformed: see error
401 credentials are required and none were sent (with a WWW-Authenticate header)
403 credentials are wrong, missing a User-Agent, or the caller isn't allowed to make this check
404 the thing asked about doesn't exist, or the player's privacy settings hide it (deliberately indistinguishable)
409 a precondition outside your request isn't met (the bot isn't in the server)
429 too many unanswered access requests at once
500 a bug on our side
502 an upstream platform (Discord, Twitch, Patreon, YouTube) failed

Versioning#

The API is versioned by path. /api/v2 is current. Within a version, responses only change in backwards-compatible ways, such as new fields or new optional parameters. Ignore fields you don't know.

/api/v1/... and the original unversioned /api/... paths are deprecated. Their responses carry:

Header
Deprecation: true the endpoint is deprecated
Link: <…>; rel="successor-version" the equivalent v2 request
Link: <…>; rel="deprecation" the migration guide
Sunset: <date> when v1 starts applying players' privacy settings (present until that date)

See Migrating to the v2 API for what changes on that date.