This article is intended to those developers who are implementing their UI applications and want to integrate the stex API into the application.
If you're developing server-to-server application please read this article instead.
The theory says: "OAuth 2 is an authorization framework that enables applications to obtain limited access to user accounts on an HTTP service. It works by delegating user authentication to the service that hosts the user account, and authorizing third-party applications to access the user account. OAuth 2 provides authorization flows for web and desktop applications, and mobile devices."
So in simple words for the end users it looks as follows:
- User clicks a button somewhere in your UI telling "Connect to STEX"
- The user is redirected to stex.com to login (if not logged in) and then to allow your application to obtain access to his/her account with specified scopes (see the screenshot below)
- User clicks "Authorize" and gets connected
Very simple and user friendly, isn't it?
From inside the things are not more complicated and the authorization flow can be implemented in few minutes at your side:
0) First of all you have to create a client at stex.com. The client ID and secret then will be used later
1) In your UI user clicks the "Connect to STEX" button.
2) You make a redirect call to https://app.stex.com/oauth/authorize with the following parameters:
'client_id' => 'client-id', <-- this is client ID of the client created at step 0
'redirect_uri' => 'https://example.com/callback', <-- this is your url to which we will redirect user after he accepts request, it should be the same that you set during client creation
'response_type' => 'code',
'scope' => 'reports',
'state' => 'some random string'
3) User confirms the request and will be redirected back to your application with authorization code and some more parameters. You should first verify the state parameter against the value that was sent to be sure the request is not fraud.
4) Then you should issue a POST request to https://api3.stex.com/oauth/token to request an access token. Your request should include the authorization code you just received. Example of the post parameters:
'form_params' => [
'grant_type' => 'authorization_code', <-- constant
'client_id' => 'client-id', <-- your client ID (the same as in first (redirect) request)
'client_secret' => 'client-secret', <-- your client secret (it was generated when the client was created at step 0)
'redirect_uri' => 'http://example.com/callback', <-- this is your url to which we will redirect user after he accepts request, it should be the same that you set during client creation
'code' => code, <-- the authorization code you've received in previous roundtrip
5) That's it! In response you will get a JSON response containing access_token, refresh_token, and expires_in attributes. The expires_in attribute contains the number of seconds until the access token expires. You can anytime obtain new access token using the reftesh_token later.
So with a help of just 2 simple requests between our applications we will exclude possible user mistakes with tokens, ensure the user will not provide you a token with wrong scopes, expired, etc.