View source for Tutorial: Connecting to the SoFurry API

This tutorial will lead you through the steps necessary to connect to the [[SoFurry REST APIs]] using OAuth 2.0.

=== Client requirements ===
*The client must be able to handle SSL certificates and HTTPS URLs.
*The client must be able to process either JSON, XML or PHP-type responses.
*The client must be registered on SoFurry and have received a client_ID and client_secret.

= Authorizing the application =

There are 2 ways to authorize your application using [[OAuth 2.0]]. SoFurry is currently only supporting "Authorization codes" for external application. "Client credentials" will be available in the future.

[[OAuth 2.0|Read more about the auth-types here]].

== Authorization code grant type ==
=== Basics ===
When using the Authorization code grant type, the auth flow is as following:

*Client sends a authorization request to https://www.sofurry.com/auth/authorize, including the client_id, client_secret and grant_type (in this case, the grant_type would be "code").
**The server answers with the HTML of the authorization page. The client must display this response and the user has to click on the "Authorize" button.
**;Authorization denied: If the users denies the authorization, the server will redirect the client to the redirect_URL (Set in the SF application manager or as a parameter in the authorization request).
**;Authorization granted: If the user grants an app access to the user data, the server will redirect the client to the redirect_URL, including the code parameter (authorization code).
*Now that the client has received the authorization code from the server, it must be exchanged for an access_token within 180 seconds (after that, the code will be invalid and the client will have to request a new one). To exchange the code with an access token, the client has to send a request to https://www.sofurry.com/auth/token, including the client_id, client_secret and the code it received before.
**The server will reply to a valid code with an access_token, refresh_token, refresh_time, and token_type. You will need the access_token to access the [[SoFurry REST APIs]]. The refresh_token can be exchanged for a new access_token later on when the access_token times out.
*After receiving the access_token, the client can now send requests directly to the [[API]] and authenticate by only including the access_token in the request parameters. A request URL for the v3 API would then look like this: https://api.sofurry.com/v3/user/details?access_token=j84u43834zhujg9u872z4.

=== Example ===
====Step 1: Client sends an authorization request to https://www.sofurry.com/auth/authorize====

Request URL (example):
 https://www.sofurry.com/auth/authorize?response_type=code&client_id=fe523da3869cfrue8hd145faf24e8366&client_secret=824013cf4et9cfe9e8c4gtr8a3f61619&redirect_uri=https://myredirecturi.com/cb&state=xyz
'''Don't forget to include the "state" parameter ("state" can be anything. This string will be sent to the redirection URL by the server [untouched])!'''

Server response (HTML preview):
[[File:OAuth authorization example.jpg|200px]]