Cannot Register using API after 2 weeks of trying

[nikiforos-dev]

Link to problem area:
It would be great to have a walkthrough of the registration flow for matrix.org using the API. This and the documentation I've found are really not making it easy. I've been working on this for two weeks trying to figoure out which docs are outdated, which blog posts are not buggy, and I can't find anything better than this: https://playground.matrix.org/#post-/_matrix/client/v3/register

Issue
Why am I getting this error when I try to verify my email address? I am able to follow the recaptcha step successfully, I can complete the terms step, but I cannot get the email verificaiton step to work at all. I've looked at all the docs after following this apparently flawed example: https://medium.com/@srijit29032001/build-a-client-app-on-matrix-network-register-user-into-the-protocol-27388d5263df.

  "error": "Unable to get validated threepid",
  "errcode": "M_UNAUTHORIZED"

I am hitting this endpoint to try and complete the registration step:

https://matrix.org/_matrix/client/v3/register?kind=user

This is the request body:

{
  "auth": {
    "session": "LLSyEToDxNOLwqLAibVfsRju", 
    "threepid_creds": {
      "client_secret": "client_secret", 
      "sid": "vUWhmHAAoQKtdZoy"}, 
      "type": "m.login.email.identity"
    }, 
  "device_id": "c58a2ddc-0494-4eda-953e-0c5f43a39632", 
  "inhibit_login": false, 
  "initial_device_display_name": "sdk_gphone64_x86_64", 
  "password": "password.123", 
  "refresh_token": false, 
  "session_id": "LLSyEToDxDOLwqLRibVfsRju", 
  "username": "username123"
}

...and I get this response:

Response (401): {
  "session": "LLSyEToDxNOLwqLRibVfsRju",
  "flows": [
    {
      "stages": [
        "m.login.recaptcha",
        "m.login.terms",
        "m.login.email.identity"
      ]
    }
  ],
  "params": {
    "m.login.recaptcha": {
      "public_key": "6LcgI54UAAAAABGdGmruw6DdOocFpYVdjYBRe4zb"
    },
    "m.login.terms": {
      "policies": {
        "privacy_policy": {
          "version": "1.0",
          "en": {
            "name": "Terms and Conditions",
            "url": "https://matrix-client.matrix.org/_matrix/consent?v=1.0"
          }
        }
      }
    }
  },
  "completed": [
    "m.login.terms",
    "m.login.recaptcha"
  ],
  "error": "Unable to get validated threepid",
  "errcode": "M_UNAUTHORIZED"
}

[nikiforos-dev]

What are the actual current steps to authorize an email at matrix.org? it seems to be a series of steps but it's not clear what those steps are

[richvdh]

I'm afraid we can't offer development support in this issue tracker. Suggest you read carefully through the documentation on User-Interactive Authentication at https://spec.matrix.org/v1.10/client-server-api/#user-interactive-authentication-api.

To validate an email address you will need to call /_matrix/client/v3/register/email/requestToken.

I'm sorry the documentation is crap. We're in the process of replacing registration with something backed by OIDC (#636), so it's not really worth expending much effort in improving right now. That said, PRs to the spec are always welcome.