Tout uses OAuth2.0 for authentication.
At first glance, it would be easy to assume that OAuth2.0 is a complicated, scary workflow with seemingly identical concepts like client_credentials and access_tokens. But OAuth2.0 is a really easy concept, and you'll think so as well in no time.
The idea behind OAuth is to remove the need for users to share their username/password combinations with multiple providers. The reason for this is because:
This is for you if:
This is for you if:
This is the most real-world authentication workflow. It assumes you want to be able to:
In OAuth, the client credentials refer to access granted to the application. This can sometimes be confusing because the word client can mean user to many people, but it is referring to the application that is acting on behalf of the user.
To successfully execute this type of authentication, you'll need both the application id (also known as a key) and secret you received when you registered your application.
I have registered an app called 'Tout IO Docs' and it has the following id and secret:
It may go without saying, but NEVER share your application id/secret pair in full with anybody. I did so because I'm foolish and trying to illustrate this flow as fully as possible :)
The next step is to make an actual request. You'll want to make a
POST request to
https://www.tout.com/oauth/token and make sure to include the following URL query parameters:
client_id- this should match your application id from when you registered the application
client_secret- likewise, this should match your application's secret
grant_type- set this to
client_credentials(hence this workflow's name).
Now when you put that all together, using the example app from above we get something like the following:
When you make the request, assuming you did it correctly you'll get a response that contains a few attributes:
While they're all important, the only thing we actually care about is the
access_token. You might say, "but won't I have to keep track the expiration date so I don't use an invalid token?". Of course, you're more than welcome to keep track of the token. However, the access_token will last for 2 years so its not really a pressing concern.
Fantastic! So now we have an access token we can make successful API read-only requests. Go ahead and try the difference:
Here's some copy-paste ready cURL commands to help you understand the requests you have to make.
The client_credentials is all well and good for getting read-only access, but that's not all that fun. We want to be able to enable users to perform Tout actions such as follow other users, or like and share Touts.
I suppose we'll need to get access on behalf of a user in that situation. There is more than one way to do this, but let's started with the easiest. The easiest is to use the URL redirection technique. We will give the user a link to authorize against Tout's API, and then they will be redirected to a URL of your choosing (remember that
redirect_uri when you registered an app) with an access_token.
Enough talk, let's a build a URL. First, let's examine the base URL.
Next, we are going to need three pieces of data this time around:
client_id - this is the same as the
Very important notice: Make sure your
redirect_uri matches exactly with the one you registered.
There are four potential options for the
scope parameter, and if you include more than one you'll want to separate them with a
So for my application that we leveraged in the first example, the authentication URL will be
When you authenticate, notice that you'll be redirected to the interactive documentation, and in the URL will be a fragment (#) followed by
access_token that represents your Tout account (or whichever user was logged in and authorized the app to act on their behalf.