endpoint POST /verify as documented in the Readme is very wrong

Start with README.md#post-verify, then compare its POST and GET descriptions with internal/api/verify.go, especially Validate() around line 85 and verifyPost around line 229. Document the actual fields, token forms, types, and branch-specific requirements, including a realistic request example; done means the README matches both endpoint implementations.

Improve documentation

Link

https://github.com/supabase/auth/blob/master/README.md#post-verify

Describe the problem

the README says the request payload needs 2 fields "type" and "token", and sometimes "password". I implemented this and got a 400 validation_failed error with the message "Only an email address or phone number should be provided on verify". this is surprising because neither email nor phone were in the docs and made a request that looks just like the example code.

I found the error message in the source: https://github.com/supabase/auth/blob/master/internal/api/verify.go
in function Validate() on line 85 at the moment. I'm not fluent in Go but this seems to be describing a VERY different set of request requirements from the docs.

looking only at the POST branch here are the problems:

1. requires one of "token" or "token_hash" (token_hash is not in the docs)
2. if token then also requires "phone" or "email" (this is the path that i'm causing) and the error message is wrong - saying the ONLY email and phone may be provided - but obviously "token" is allowed - and the docs clearly say "type" and "password" too. (is the readme just completely wrong?)
3. if token_hash then it requires there not be 'email', 'phone', nor 'redirect_to'. (none of this is in the docs)
4. in the verifyPost function (line 229) you can see that the "type" can be : signup, invite, recovery, magiclink, email_change, sms, or phone_change. the docs say only signup or recovery or invite (in POST) and in GET adds magiclink. This is a mess.
5. the readme does not mention request fields : token_hash, email, phone, or redirect_to but ALL of those are important in different ways. Further, the docs mention that sometimes "password" is required but this doesn't seem to be in the code at all.

(aside) note that the GET branch requires "token" but then it treats it as a "token_hash" too.

Describe the improvement

1. fix the docs to actually describe the required input to the POST and GET /verify endpoints.
2. It's a little ambiguous just what type of "token" is needed since the confirmation code email can send a token hash or a token.
3. a single realistic example would clear this all up.

Additional context

here is a slightly redacted version of my request:

POST https://xxxxxx.supabase.co/auth/v1/verify

Headers:
  authorization: Bearer 
  apikey: sb_publishable_SA_xxxxxxxxxxxxEW-_R

Body:
{
  "type": "signup",
  "token": "bb7895c199b69e859xxxxxxf86e373ff9db3a090ea3a99d741"
}

and the response:

{
  "code": 400,
  "error_code": "validation_failed",
  "msg": "Only an email address or phone number should be provided on verify"
}

This seems to be so broken that I might be making some very silly mistake. help!