gd auth

gd-auth.md

DashAuth API

Warning

If you are a modder or a developer, please tell me what you think of the current specification and if/how it can be improved!

All responses use JSON as data type. ## Types

Token (used for client->3rd party requests): Bearer <random string>

Challenge:

Field	Type	Description
bot_account_id	u32	Account ID of the Geometry Dash bot account that will validate the client
challenge	String	Randomly generated string (at least 8 characters, ASCII only) that will be sent to the bot for validation
id	UUID	Random UUID that indicates a specific challenge, used to make the backend check if a challenge has been completed

Routes

GET [base url]/request_challenge/<gd account id>

Returns a Challenge

GET [base url]/challenge_complete/<challenge id>

Returns:

• 200 Ok and a Token if successful
• 404 Not Found if the challenge wasn't found
• 401 Unauthorized if the challenge has not been validated.

side notes

It is recommended to return data in the following format:

{
  "success": bool,
  "message": "error description if failed",
  "data": "result data as json object (or string if token) if successful"
}

upcoming

• different format for URLs (e.g. [base url]/request_challenge?acc=<gd account id> instead of arguments as paths)
• specifics about server side implementations (challenge expiration, etc)

existing implementations

Project	Developer	Environment	Language	Notes
dashauth	rooot	Client	C++	Official client API implementation
dashend	rooot	Server	Rust	Backend for my GD mods, uses auth

If you're a developer implementing this spec in your project and want it listed here, feel free to comment or to contact me

I'm lookng at this once again, and this time I'm leaving this here as a helpful resource, extending your diagram from discord a bit by including server-gd communication.

sequenceDiagram
  participant Client
  participant Server as Auth server

  note over Client: wants the Server to perform<br/>an action as the owner of AID

  Client->>+Server: /request_challenge/{AID}
  Server->>-Client: bot_account_id, challenge, id

  create participant Bot as GD auth bot account<br/>(bot_account_id)
  Client->>Bot: uploadGJMessage "{challenge}"
  note over Bot: getGJMessages
  destroy Bot
  Bot->>Server: {AID} completed {id}

  note over Server: is now proven that<br/>the Client owns the AID

  Client->>+Server: /challenge_complete/{id}
  Server->>-Client: token

  Client-->>+Server: request, token
  note right of Server: knows this is actually AID,<br/>performs action
  Server-->>-Client: response to an authorized request

Issues this authorization solves (that I could think of) are:

1. as a client, trusting a non-gd server to not steal your account login info.
2. as a gd mod, trusting loginGJAccount to be the authentic one.

those 2 points are the reason i made this lmao (ty for the diagram btw!!)