Tutorial: Connecting to the SoFurry API

From SoFurry
Revision as of 09:40, 6 March 2016 by TerraBAS (talk | contribs) (→‎Step 1: Client sends an authorization request to https://www.sofurry.com/auth/authorize)
Jump to: navigation, search

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.

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):

Error creating thumbnail: File missing
Retrieved from "http://wiki.sofurry.com/w/index.php?title=Tutorial:_Connecting_to_the_SoFurry_API&oldid=1975"