Improve OAuth docs

[llrs]

This issue explores how to manage refresh tokens with httr2 (linked to #316 questions) created with oauth_flow_auth_code.

When a website provides a token with a changing refresh token I haven't found a method without requesting confirmation from the user:

• oauth_flow_auth_code: Create a new token, so it needs to be validated again in the browser by the user when updating it.
• oauth_flow_refresh: Should not be used
• req_oauth_auth_code could cache the token but it would revert to oauth_flow_auth_code when enough time passes.
• I haven't find other functions are meant for this kind of authentication.

I was using oauth_flow_refresh because it was the only way to self-manage the tokens without asking for confirmation from the user. It is unclear to me if req_oauth_auth_code would overwrite the token store the token too shortly.

In short, I wish to be able to refresh a token and self-manage it.

---

In addition, I think I was confused by the name of the function req_auth_bearer_token, which should be used for all tokens. Maybe req_auth could be a better name if a single function could handle all the token types (without needing to to something like token$access_token like in the vignettes).

As a summary I made while looking into this, in case someone else finds it helpful:

Obtain token	Update token	Authenticate token
oauth_flow_client_credentials()	req_oauth_client_credentials()	req_auth_bearer_token()
oauth_flow_device()	req_oauth_device()	req_auth_bearer_token()
oauth_flow_bearer_jwt	req_oauth_bearer_jwt()	req_auth_bearer_token()
oauth_flow_password()	req_oauth_password()	req_auth_bearer_token()
oauth_flow_refresh()*	req_oauth_refresh()	req_auth_bearer_token()
oauth_flow_auth_code()	req_oauth_auth_code()	req_auth_bearer_token()
oauth_flow_device()	req_oauth_device

*: Shouldn't be used except for testing interactively.

Usually the req_auth_* function is only mentioned on the auth_flow_* function help pages. But not the other way around: the req_auth_* do not mention auth_flow_*.

[hadley]

In general, you shouldn't be using any oauth_flow_* to obtain the token or req_auth_bearer_token() to authenticate with it. The only function you should need is req_oauth_*(), which you pick based on the style of OAuth you need for a specific API.

I think the big question here is why you want to self-manage tokens — that really fights against the goal of httr2 to do that for you. (And in general, I don't think you can provide a good user experience when self-managing tokens because you need to be able to automatically re-auth if a token expires, and that has to be done by httr2 since it's in the middle of the request flow.)

Could you give me a high level view of what you're trying to achieve so that I can steer you in the right direction?

[llrs]

I want to self-manage tokens because 1) with httr is what I used to do, 2) with a changing refresh token until #232 there was no way for httr2 to handle it, so I had to implement it myself, 3) because from the vignette I understood that oauth_flow_* was the safest path.

I used to re-auth automatically before hitting the API by requesting a fresh token and replacing the old one to store the new refresh token. If not possible, I requested a new token before making the call to the API. As noted in #319, it used to work.

I see I made several bad decisions because I didn't understood correctly the documentation. Apologies for all the opened issues in these days

[hadley]

I don't think it's your problem; it's mine — I seem to have failed to document how I expect folks to actually do OAuth, which has lead to a lot of confusion. I'll see what I can do to improve the documentation — I think it probably makes sense to document (e.g.) oauth_flow_device() with req_oauth_flow_device() and make it clear that I expect you to only use the oauth_* functions when debugging the initial token fetch.