Authentication Flow (Gateway)

1. Redirect the user to MinecraftID

https://api.minecraft.id/gateway/start/{username}

Parameters

Name	Type	Description
username	string	The username to authenticate
callback	string	An URL to send the user to after the authentication is finished
style	string	(optional) simple for simple style

• This request will either trigger a new authentication in Minecraft (the user has to login to Minecraft), or call the callback URL immediately if the authentication is still valid

2. User is redirected back to the callback URL

<Callback URL>

Parameters

Name	Type	Description
Callback URL	string	URL you provided in the first step
mcauth_success	boolean	Whether the authentication was successful
mcauth_status	string	Either VERIFIED if the username was verified, NOT_VERIFIED if the username could not be verified, or ERROR if an error occurred
mcauth_msg	string	Additional information
mcauth_code	string	If the authentication was successful, the code used to verify

3. You check against the API if the authentication is valid

POST https://api.minecraft.id/gateway/verify/{username}

Parameters

Name	Type	Description
username	string	username to verify
code	string	code returned with the previous redirect

Returned Parameters

Name	Type	Description
valid	boolean	Whether the request is valid & the username was successfully confirmed

Notes

• The code returned by step #2 is temporary and not intended to be stored by your application. It will expire right after you call the verify-route
• If you need to verify access to your application multiple times, you should create your own credentials and store it e.g. in the user's cookies
• To renew the user's code, you can simply redirect the user to the start-route once again - if the authentication did not yet expire on MinecrafTID, you will immediately receive another callback with a new code