TreatStream

Getting started with Oauth 2 on TreatStream

Although most of the data on the TreatStream API is readable by providing only your API Key, some information requires authentication.

To access endpoints with authentication, you must create your Oauth Client and save your redirect URLs in your TreatStream API settings.
Then follow these steps :

Important parameters like Client Id, Client Secret, Redirect Url that used futher in process can be get from Account Setting page.

1. Send your user from your application to our Authentication url

Url :

https://treatstream.com/Oauth2/Authorize Request example : curl -X GET https://treatstream.com/Oauth2/Authorize?response_type=code&client_id= {your-client-id}&redirect_uri={your-redirect-url}&state=6ecf9c364982a5a7&scope=

Request query parameters :

Parameter	Type	Required?	Description
response_type	String	Yes	The "response_type" parameter in an OAuth 2.0 authorization URL specifies the desired response type from the authorization server eg. `code, token`.
client_id	String	Yes	The "client_id" parameter in an OAuth 2.0 authorization URL is used to identify the client application making the authorization request.
redirect_uri	String	Yes	The "redirect_uri" parameter in an OAuth 2.0 authorization URL specifies the URI (Uniform Resource Identifier) to which the authorization server should redirect the user after the authentication or authorization process is complete.
state	String	Yes	The "state" parameter in an OAuth 2.0 authorization URL is used for maintaining the state of the client application between the authorization request and the callback. The "state" parameter is used to `protect against CSRF.` Your application generates a random string and sends it to the authorization server using the state parameter. The authorization server sends back the state parameter. If both state are the same => OK. If state parameters are different, someone else has initiated the request.
scope	String	Yes	The "scope" parameter in an OAuth 2.0 authorization URL is used to specify the scope of access requested by the client application. The "scope" defines the level of access and the types of operations that the client is requesting authorization for. Example value for this field is `userinfo`

Don't forget to save the redirect url in your settings first.

After accepting your application, the user will be sent to your redirect url with a code parameter :

{your-redirect-url}?code=....

The "code" parameter is used to identify user and protect user access token, You can get access token in exchanges of code. The code value will be available only for few minutes of time for you to securly exchange access token.

Response example :

https://{your-redirect-domain}/?code=1e16cd4e1035d391655956fac187a1e2b3a257bf &state=6ecf9c364982a5a7

2. Post the provided code to our OAuth Token url

NOTE: Access Token will be expired in 30 Days.

Url :

https://treatstream.com/Oauth2/Authorize/token

Request POST parameters :

Parameter	Type	Required?	Description
code	String	Yes	The "code" parameter in the POST request serves as the authorization code obtained during the OAuth 2.0 authorization process, allowing the server to exchange it for an access token.
client_id	String	Yes	The "client_id" parameter in the POST request is the unique identifier assigned to your application during OAuth 2.0 registration.
client_secret	String	Yes	The "client_secret" parameter in the POST request is a confidential key known only to the OAuth 2.0 client and authorization server. It's used for securing the communication between the client and the server during the token exchange process.
redirect_uri	String	Yes	The "redirect_uri" parameter in the POST request specifies the callback URL where the authorization server redirects the user after authentication.
grant_type	String	Yes	The "grant_type" parameter in the POST request indicates the type of OAuth 2.0 grant being used, such as `"authorization_code"` in this case.
scope	String	Yes	The "scope" parameter in the POST request defines the access level requested by the client, specifying which resources or actions it wants permission to access. Example value for this field is `userinfo`

Request POST parameters example : -X POST https://treatstream.com/Oauth2/Authorize/token \ -H "Content-Type: application/json" \ -d '{ "code": "<Code>", "client_id": "<Client-ID>", "client_secret": "<Client-Secret>", "redirect_uri": "<Redirect-URI>", "grant_type": "authorization_code", "scope": "userinfo" }'

Response Body :

Field	Type	Description
access_token	String	The "access_token" in the OAuth 2.0 response serves as a credential, permitting authorized requests to protected resources.
expires_in	Integer	The "expires_in" field helps in managing the security of the authentication process by imposing a time limit on the usability of the access token, thereby reducing the risk associated with long-lived tokens.
token_type	String	The "token_type" field, set to "Bearer" in OAuth 2.0 responses, instructs the client to include the access token directly in the Authorization header of HTTP requests, simplifying authentication without additional credentials.
scope	String	The "scope" field in an OAuth 2.0 response specifies the access rights of the access token, with `"userinfo"` typically granting access to user profile information. Scopes control permissions, allowing users to grant or deny specific access during the authorization process.
refresh_token	String	The "refresh_token" in the OAuth 2.0 response enables a client application to obtain a new access token without user reauthentication, extending access beyond the expiration of the initial token. The "refresh_token" will `expire after 180 days.`

Response example :

{ "access_token":"005aa8eef475f96b3c873c34df58803cab530ed0", "expires_in":864000, "token_type":"Bearer", "scope":"userinfo", "refresh_token":"8a2a65e3ffb125bef3b917c8d624ecd5bc0c534rd" }

3. Get the user's treats with the access_token

NOTE: You will get last month(30 days) received treat data from today.

You can add the access_token in a query string when you read the API endpoints.

Url

https://treatstream.com/api/getMonthTreats/{your-access-token} Request example : curl -X GET https://treatstream.com/api/getMonthTreats/005aa8eef475f96b3c 873c34df58803cab530ed0

Request Query parameters

Parameter	Type	Required?	Description
access_token	String	Yes	Replace "{your-access-token}" in the URL with your actual access token for authentication when making the API request.

Response example :

[ { "message": "sample treat", "sender": "treatstream", "sender_type": "f", "receiver": "kumokgb", "receiver_type": "t", "date_created": "2024-03-04 12:34:56", "title": "fried potato stick and orange drink" }, { "message": "sample treat2", "sender": "treatstream", "sender_type": "t", "receiver": "kumokgb", "receiver_type": "t", "date_created": "2024-03-11 12:28:47", "title": "bacon and salad roll" } ]

If something is wrong with parameters appropriate error message will be given in response.

4. Refresh user's token

NOTE: Refresh Token will be expired in 180 Days.

Url :

https://treatstream.com/Oauth2/RefreshToken

Request POST parameters :

Parameter	Type	Required?	Description
client_id	String	Yes	The client_id is a unique identifier assigned to the client (your application) during the OAuth 2.0 registration process. It is used in the token refresh process to authenticate and identify the client, ensuring secure communication with the authorization server.
client_secret	String	Yes	The client_secret is a confidential credential known only to the authorized application and the authorization server. It serves as a means of authenticating the client during the OAuth 2.0 token exchange, enhancing the security of the communication between the client and the server.
refresh_token	String	Yes	The `refresh_token` is a long-lived credential obtained during the OAuth 2.0 authorization process. It allows the client to request a new access token without requiring user reauthentication, providing a mechanism for continuous access to protected resources while enhancing security by reducing the exposure of access tokens.
grant_type	String	Yes	The `grant_type` in OAuth 2.0 specifies the type of authorization grant used by the client to obtain an access token. For a token refresh, the `grant_type` is set to `'refresh_token'` indicating that the client is requesting a new access token using a previously obtained refresh token.

Request POST parameters example : curl -X POST https://treatstream.com/Oauth2/RefreshToken \ -H "Content-Type: application/json" \ -d '{ "client_id": "<Client-ID>", "client_secret": "<Client-Secret>", "refresh_token": "<Refresh-Token>", "grant_type": "refresh_token" }'

Response Body :

Field	Type	Description
access_token	String	The `access_token` in the response is a bearer token that authorizes the client to access protected resources on behalf of the user. It is included in API requests to authenticate and authorize the client, ensuring secure communication between the client and the resource server.
expires_in	Integer	The `expires_in` in the response indicates the duration in seconds for which the access token is valid. It helps the client manage token expiration by specifying the time remaining until the token becomes invalid, prompting timely refresh requests for continuous access to protected resources.
token_type	String	The `token_type` in the response specifies the type of token issued, typically set to `'Bearer.'` It indicates the authentication mechanism used by the client when including the access token in API requests, allowing the resource server to validate and authorize access to protected resources.
scope	String	The `token_type` in the `scope` field indicates the type of access associated with the access token. In OAuth 2.0, when the token type is 'Bearer' in the scope, it signifies that the token grants access to protected resources using the Bearer token authentication method.
refresh_token	String	The `refresh_token` in the `scope` field indicates that the access token response includes a refresh token. This allows the client to obtain a new access token without user reauthentication, enhancing the security and longevity of the authorization process. The "refresh_token" will `expire after 180 days.`

Response example :

{ "access_token":"005aa8eef475f96b3c973c34df56603cab300cd0", "expires_in":864000, "token_type":"Bearer", "scope":"userinfo", "refresh_token":"8a2a65e3ffb125bef3b917c8d624ecd5bce230b2" }

Socket Token

1. How To Generate Socket Token

Url :

https://treatstream.com/Oauth2/Authorize/socketToken

Required POST parameters : Params: {client_id: Client ID, access_token:Access Token} Response example :

{"socket_token":Socket Token}

2. How To Use Socket Token

This is built using node-js, so you need to handle it with javascript. Include the script below in your html, and then handle real-time Treat data in 'realTimeTreat' event. This event will be invoked whenever any Treat is received.

<!-- Include Socket.io library -->
                <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/1.7.2/socket.io.min.js"></script>
                <!-- Initialize Socket.io connection -->
            <script type="text/javascript">
                       // Initialize Socket.io connection with the specified URL and token
                       var socket = io('https://nodeapi.treatstream.com/',
                       {query:"token=SocketToken"});
                       // Connect to the socket
                       socket.connect();
                       // Event listener for successful connection
                       socket.on('connect', function (data) {
                               // Log connection status
                               console.log("connected");
                       });
                       // Event listener for receiving real-time treat data
                       socket.on('realTimeTreat', function (data) {
                               //Handle realtime treat data here
                               console.log("treatdata ",data);
                       });
            </script>

Real time treat data example :

{ "message" : "enjoy treat", "sender" : "treatstream", "receiver" : "kumokgb", "title" : "Pizza", "sender_type" : "Twitch", "receiver_type" :"Twitch", "date_created" : "2024-03-16 14:21:44" }