Headless Flow

This guide explains how to implement the headless authentication flow using the MC-ID API.

View API Reference

Comparison with Normal Mode

Feature	Normal Mode (OIDC)	Headless Mode
User Experience	Single Sign-On (SSO). Users verify once and can log in to any MC-ID app without re-verifying.	Per-App Verification. Users must launch Minecraft and verify specifically for your app every time.
Integration	Standard OIDC libraries.	Manual API calls.
Security	Handled by MC-ID.	You handle the flow.

The Flow

Request Code: Your app requests a verification session for a Minecraft user.
User Joins Server: Instruct the user to join the Minecraft server, auth.mc-id.com.
User Receives Code: The server kicks the user and displays a 6-digit code.
User Enters Code: The user enters this code into your application.
Verify Code: Your app sends the code to the API for verification.

Step 1: Request Code

Call the codes/request endpoint with the user’s UUID to start the process.

curl -X POST https://mc-id.com/api/v1/codes/request \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"uuid": "069a79f444e94726a5befca90e38aaf5"}'

Step 2: User Joins Server

Instruct the user to join the verification server, auth.mc-id.com.

Step 3: User Receives Code

The user will be kicked from the server with a message containing their verification code.

Step 4: Verify Code

Once the user enters the code in your app, call the codes/verify endpoint.

curl -X POST https://mc-id.com/api/v1/codes/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"code": "123456", "uuid": "069a79f444e94726a5befca90e38aaf5"}'

If successful, the user is verified for your application.