Document other endpoints

[synedra]

We have good documentation about the OAuth endpoints, including the request and the response.

https://fusionauth.io/docs/lifecycle/authenticate-users/oauth/endpoints

We should document our other relevant endpoints using the same format on pages with the path/title of 'endpoints', including the purpose of the endpoint, the request parameters and the response.

They should be added under the appropriate documentation category.

Here are endpoints we should document:

Under https://fusionauth.io/docs/lifecycle/manage-users/account-management/

the account endpoint

Note that this is a feature only available with a paid edition, so we should use the correct blurb.

Under https://fusionauth.io/docs/lifecycle/register-users/

the registration endpoint

Under https://fusionauth.io/docs/lifecycle/authenticate-users/saml

the SAML ACS and other endpoints

You'll want to break out https://fusionauth.io/docs/lifecycle/authenticate-users/saml#endpoints

Under OAuth

the OAuth2 callback (/oauth2/callback)

This is the callback if FusionAuth is a client (so if you are federating from one FusionAuth instance to another, this would be the redirect URL. See https://fusionauth.io/community/forum/topic/826/can-fusionauth-federate-to-itself/4 for more.)

[sixhobbits]

@synedra - would you be able to help with any more input on this one based on the below? I think we might need source code access to do this one properly, but let me know if you have more inputs and we can make an attempt.

Questions

• Why are some APIs documented under the API category, and some in other documentation sections? For instance, the OAuth API. All APIs should be under https://fusionauth.io/docs/apis to make it easy for readers to find all the ways of interacting with FA using an API in one section.
• Similarly, why isn't the OAuth API (and perhaps other APIs I haven't found that are not listed under the API documentation category) not documented in the OpenAPI schema? I think we should open an issue to do this.

Requests in this issue and problems:

• Document /account in docs at /docs/lifecycle/manage-users/account-management
  • But that's not an API, that's a webpage. /account redirects you to generic welcome page in FA. There is no /account endpoint in the docs or in FA as far as I can see
• Document the registration endpoint at https://fusionauth.io/docs/lifecycle/register-users
  • But this is already documented at https://fusionauth.io/docs/apis/registrations, and it's linked correctly from the docs at https://fusionauth.io/docs/lifecycle/register-users. What more is there to do? Duplicate the API docs rather than link them? I think that would make the documentation worse.
• Document SAML at https://fusionauth.io/docs/lifecycle/authenticate-users/saml
  • But SAML is already documented at https://fusionauth.io/docs/apis/identity-providers/samlv2, same problem as above.
• Document /oauth2/callback at https://fusionauth.io/docs/lifecycle/authenticate-users/oauth/endpoints
  • This request is mostly fine. The endpoint is not documented and should be. However, the OAuth specification does not strictly define requests, responses, data types and errors, so without access to the FA source code, I'm going to have to experiment with an instance and hope I can get the API definition roughly correct.