How to Integrate an Emulator with retroshelf
Use retroshelf's integration API to link a user's account, identify played games, and send play session history from an emulator, launcher, or device plugin.
Overview
retroshelf integrations let emulators, launchers, and device plugins send play sessions into a user's shelf. The integration should do three things:
- Link the user's retroshelf account with a short-code flow.
- Send play sessions when a game ends, or sync missed sessions later.
- Include enough game metadata for retroshelf to match the session to the right game.
The developer API reference lists every endpoint with request and response examples, and the retroshelf Postman collection lets you try them.
What to request
Submit the developer integration application to request integration access. Include:
- Emulator, launcher, or plugin name
- Project website, GitHub repo, or download page
- Maintainer name and contact email
- Supported platforms or firmware
- Brief description of how you will collect play session data
- Local testing needs, if any
retroshelf will email the approved client details to the maintainer email on the application.
Authentication
Use the OAuth 2.0 Device Authorization Grant, defined by RFC 8628. This is the right fit for emulators and handheld devices because the user can approve the link on a phone or computer.
Request a device code
Call the device-code endpoint with the client ID retroshelf gives you.
POST /api/auth/device/code
Content-Type: application/json
{
"client_id": "rs_your_client_id"
}Show the user code
Display the returned code and verification URL inside your emulator or plugin.
{
"device_code": "internal-device-code",
"user_code": "483921",
"verification_uri": "https://retroshelf.org/link",
"expires_in": 1800,
"interval": 5
}Tell the user to visit retroshelf.org/link, sign in, and enter the code.
Poll for tokens
Poll the token endpoint at the returned interval until the user approves the integration.
POST /api/auth/device/token
Content-Type: application/json
{
"grant_type": "urn:ietf:params:oauth:grant-type:device_code",
"device_code": "internal-device-code",
"client_id": "rs_your_client_id"
}Store the access token securely. The current plugin flow uses that bearer token for sync-client API calls.
Complete the link
After token approval, call completeLink to register or reconnect the emulator installation. Store the returned syncClientId; every sync request must include it.
The current supported platform values are onionos, knulli, muos, rocknix, android, spruceos, batocera, steamos, and nextui.
POST /api/syncClient/completeLink
Authorization: Bearer access_token
Content-Type: application/json
{
"name": "ExampleEmu",
"platform": "muos",
"fingerprint": "stable-device-id",
"deviceSlug": "trimui-smart-pro",
"metadata": {
"version": "1.2.3"
}
}{
"syncClientId": "sync_client_id",
"lastSyncCursor": null
}Send play sessions
Send sessions after the user exits a game. If the device was offline, queue sessions locally and retry later with the same session fields.
POST /api/syncClient/syncSessions
Authorization: Bearer access_token
Content-Type: application/json
{
"syncClientId": "sync_client_id_from_completeLink",
"sessions": [
{
"romPath": "steam/367520",
"romName": "Hollow Knight",
"steamAppId": "367520",
"duration": 5400,
"devicePlayedAt": 1781229600,
"platformHint": "steam"
}
]
}{
"submitted": 1,
"created": 1,
"synced": 1,
"matched": 1,
"unmatched": 0,
"results": []
}submitted is the number of sessions accepted in the request. created is the number of new raw
sessions stored after deduplication. synced is the number accepted for matching in this request,
including an idempotent retry that was already stored but still pending.
Recommended fields
At minimum, send:
syncClientIdsessions[].romPathsessions[].durationsessions[].devicePlayedAt
devicePlayedAt is the Unix timestamp, in seconds, when the session started. RetroShelf derives the
session end by adding duration.
Send these when available:
sessions[].romNamesessions[].romHashsessions[].steamAppIdfor exact native Steam game matchingsessions[].platformHint
Game matching
retroshelf first uses steamAppId for exact native Steam game matching. Otherwise, it normalizes
romName when present, or the filename from romPath, then searches retroshelf's game catalog.
Sessions that cannot be matched are still stored as raw sync sessions. When romHash is a valid MD5,
retroshelf may use Hasheous as a final exact-match fallback and retain a successful match for future
syncs. platformHint narrows catalog searches but does not override an exact hash match.
Do not block a session just because optional metadata is missing. Send what you know, and retroshelf will preserve the raw data.
Integration checklist
- Request integration access through the developer integration application.
- Implement OAuth 2.0 Device Authorization Grant.
- Store tokens outside public config files.
- Queue sessions while offline.
- Retry with the same
romPath,devicePlayedAt, anddurationvalues for deduplication. - Send MD5 ROM hashes when your platform can compute them.
- Keep API calls in the background so gameplay is never delayed.
Questions
Do I need a client ID before building an integration?
Submit an integration application with your emulator or app details. Client access is reviewed manually while the integration API is early.
What OAuth flow should an emulator use?
Use the OAuth 2.0 Device Authorization Grant from RFC 8628. It lets the emulator display a short code while the user approves access from a phone or computer.
Do I need perfect game metadata?
No. Send the ROM path, ROM name when available, duration, and played-at timestamp. When an MD5 hash is available, retroshelf may also use Hasheous to identify an otherwise unmatched game.