Lets say you want to use google as an auth provider. You do this:
"Hey google who is this guy? I'm going to send them to google.com/oauth, send them back to example.com/oauth, and in the headers of the request include the word "Authorization: bearer" followed by a bunch of text"
Google says "Oh yeah I know that guy, here I'll send them back to where you said with a token"
Then later on you can take the token and say "Hey google, somebody gave me this token, who is it?"
That's pretty much it. You have to trust that google isn't lying to you, but that's kindof the point of oauth.
But that's never what the documentation says. It's always 10 pages long and the examples are like "here's a fully functioning python web server using flask and function decorators, oh the actual auth flow, which is really like 3 lines of code, is hidden inside of a library".
To people who write documentation: PLEASE for the love of god show me how to talk to your API both using your library, but also using something like urllib2 or requests or something.
Ideally the documentation is the absolute most minimal way of making the service work, and then adds more and more usefulness on top of that. I'm not going to judge you for writing bad code in an example. The example could practically be pseudocode for all I care. I just want to see generally how your API is supposed to work.
edit: yes, auth0, I am looking at you.