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.

[bradmccarty]

@mark-robustelli Please see the above and advise @sixhobbits. It is possible that this is outside the scope of their ability, because they might need codebase access. If that is the case, please close this and let's move it back internal.

[mark-robustelli]

@synedra , I can see @sixhobbits point of view. Are you OK closing this? Maybe opening another issue for the call back documentation?

[synedra]

This was originally opened by @mooreds - let's give him a moment to weigh in on this as well. Since I'm working on more front-loaded things I can't get to this for a while myself, but let's see if we can address the issues themselves.

[mark-robustelli]

@mooreds , I don't think we want to duplicate documentation so it sounds like the only thing left is to update the Document /oauth2/callback, does that sound about right?