Back
Home
Modal text placeholder
By using FineFriends, you agree to our cookie policy.
FineFriends is undergoing maintenance. You cannot login until this is finished. We're back soon!

OAuth2

Get information of a user and use FineFriends to login to your application

General Documentation (V4) Documentation (V3)

OAuth2

Using our OAuth2 API, you can retreive information from FineFriends. You can use it to let your users sign in to your application.

Getting started

The first step in implementing OAuth2 into your application, is registering a new application in the developer portal. After entering the basic details, you will receive the App ID and App Secret. As the name implies, your App Secret is SECRET! Never, ever put it in a place where users or other malicious actors can access it!

After you created your app, click 'Change Settings'. Here you can add a logo for your application. You can also add one or more allowed redirect URI(s). This is the URI that the user will be redirected to after authorization. It is required to add at least one URI in order for you app to work.

If you are implementing OAuth2 into your application, you should be able to use a library for the language of your choice. You can also implement it from scratch.
For the specific implementation, please see the tabs above for the documentation of the version that you are using. See below for more information about the different versions.

Available versions

There are multiple versions of the API. In the table below, you can find the status of the different versions. Please make sure to always use the latest version, even if another version is still supported. This way, you can use all the latest functionality and updates.

Version Status
4 Available
3 Available (To be deprecated soon!)
2 Discontinued
1 Discontinued

How to implement the API

You can implement the FineFriends API with your own application. For example, you can use it to let your users sign in using their FineFriends account.

If you want to use FineFriends to let your users sign in, you will need to add an extra column to your databse where you store the user id of the FineFriends account. You cannot use the username or email address to identify a user, since these might change. As long as a user has a FineFriends account, the ID stays the same. If you want to create a new account using this method, you can use the email address, display name and username, but you still need to use the user ID to identify the FineFriends account. Never use the FineFriends user ID as the user ID for the accounts your own application.

How do I manage my apps?

You can manage your apps on this page.

Getting started (V4)

Version 4 has some small changes compared to version 3 Most notable is that the user data is no longer inside an JSON-object, but it is now just in the JSON root.

Make sure that you have followed the instructions on the General tab first!

Start the authentication

Before you can get access to information of a user, the user needs to give your app permission to access the account. Tho start the authentication process, you redirect the user to the authorization page. Example:

https://finefriends.social/api/v4/auth?client_id={YOUR_APP_ID}&response_type=code&state={NONCE}&redirect_uri={REDIRECT_URI}

You can easily generate a authorization URL by opening your app from the My Apps page, and using the OAuth2 URL Generator.

Once the user clicks the link, the authorization page will be opened. If the user authorizes the app, he/she will be redirected to the Return URL with the GET parameters 'code' and 'state'. You need this for the next step. If you did send a 'state' paramater, it will be set as well. In that case, check if the state is exactly the same as when it was generated. If they do not match, it's possible that someone intercepted the request or otherwise falsely authorized themselves to another user's resources, and the request should be denied. Example:

https://your.website/oauthCallback?code=abcdefgh12345678&state=XXXX

If the user does not authorize the app, he/she will be redirected to the Return URL with the GET parameter 'error' and value 'access_denied'. Example:

https://your.website/oauthCallback?error=access_denied

Exchanging for access token

The authorization code that you received, needs to be exchanged for an access token. You do this by making a POST request to the Token URL with the following parameters:

  • client_id
    • This is the public App ID.
  • client_secret
    • The App Secret.
  • grant_type
    • This always needs to be 'authorization_code'.
  • code
    • The code that your received after authorization.
  • state
    • The state that you used for authorization. Also include this if you did not use a state for authorization, in that case you simply pass a empty string.
  • redirect_uri
    • The redirect_uri that you used for authorization.

Below you can find an example for exchanging the code for a access token:

<?php
$url_gettoken = 'https://finefriends.social/api/v4/access_token'; //Do not change this URL
$data_gettoken = array(
    "client_id" => "YOUR_APP_ID", //Your application id
    "client_secret" => "YOUR_APP_SECRET", //Your application secret
    "code" => $_GET["code"], //The GET parameter you got in the callback
    "state" => $_GET["state"], //The GET parameter you got in the callback
    "grant_type" => "authorization_code", //Do not change this
    "redirect_uri" => "YOUR_REDIRECT_URI", //Needs to match the redirect_uri used in the autorization process
);

$ch_gettoken = curl_init($url_gettoken);
curl_setopt($ch_gettoken, CURLOPT_POST, true);
curl_setopt($ch_gettoken, CURLOPT_POSTFIELDS, $data_gettoken);
curl_setopt($ch_gettoken, CURLOPT_RETURNTRANSFER, true);

$payload = curl_exec($ch_gettoken);

$json = json_decode($payload, true);
if(!empty($json['access_token'])){
    $access_token = $json['access_token'];
}
?>

This will create a one-time access token and get the information from FineFriends. Please note that a authorization code has a lifespan of 30 seconds, after that you will need to perform the authorization process again.
The response that includes the access token looks like this:

{
 "api_version": "4.1",
 "api_status": "success",
 "access_token": "74cb2eb6ab29487729e38483c9ccdd4e8b328ce8ff22e430dbb0e6cdc0763dd5e2c622d24f2d79f40010df95c0e10a05d991",
 "token_type": "bearer"
}

Retreive the information

The access token allows your application to retreive information from the user_info endpoint. You do this by making request with the access token in the Bearer Autorization header:

Authorization: Bearer 74cb2eb6ab29487729e38483c9ccdd4e8b328ce8ff22e430dbb0e6cdc0763dd5e2c622d24f2d79f40010df95c0e10a05d991

An example where this is implemented is below:

<?php
$url_getinfo = 'https://finefriends.social/api/v4/user_info'; //Do not change this URL
$ch_getinfo = curl_init($url_getinfo);
curl_setopt($ch_getinfo, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch_getinfo, CURLOPT_HTTPHEADER, array(
    'header' => "Authorization: Bearer ".$access_token, //Set the access token you received as the authorization header.
));
$data = json_decode(curl_exec($ch_getinfo), true);
?>

Using the information

The information returned by the API is formatted in JSON:

{
 "api_status":"success",
 "api_version":"4.1",
 "id":"{ID of the user}",
 "name":"{Display name of the user}",
 "email":"{Email address of the user}",
 "username":"{Username of the user}"
}

To use this information, you use the json variable in the code above. For example, if you want to use the users email address, you can use the following snippet:

$data['email'];

For testing, you could use the following code. It shows the name, username and password of the FineFriends account.

echo 'Hello, '.$data['name'].'. Your username is '.$data['username'].' and your email address is '.$data['email'];

Debugging and error handling

If you do not get the expected results, we offer some debugging and error handling options. If an error occured during the authentication, the response will look like this:") ?>

{
 "api_status":"error",
 "api_version":"4.1",
 "error":"invalid_client"
 "error_description":"No client id given!"
}

Every error that occures within the API will be marked using api_status 'error'. The value for error indicates the general error that occured and the error_description gives a human-readable explanation for what went wrong.

To implement error handling, you can use the following code for checking the response:

if($json['api_status']=="success"){
 //Get info here
} else {
 //Do your error handling here
 //Uncomment following 2 lines to echo the error message
 //echo $json['error'];
 //echo $json['error_description'];
}

If the user does not authorize the app, he/she will be redirected to the Return URL with the GET parameter 'error' and value 'access_denied'. Example: https://yourdomain/?error=access_denied. You should include a check on the return URL to detect when the user has denied access.

if(isset($_GET['error'])&&$_GET['error']=='access_denied'){
 //Inform user that access has been denied.
} else {
 //Rest of the code
}

Getting started (V3)

Please consider updating your API implementation to the latest version (V4). V3 is supported for now, but it might be deprecated soon. Do not use this version if you are implementing the API for the first time.

Starting with version 3, the API is compatible with the oAuth 2.0 standards.
You will need to make some changes if you used version 2 before.

To start using the API, you will have to create an app. You can do that on this page.

You will need to enter the name of your app, a public URL and a return URL.
People will see the name of your app when they review it before giving permission to their account. When they click the name of your app, it will take them to the public URL of your app. The return URL will be the page on your website that handles the request. You can change all of these settings later.

After creating the app, you will see an App ID and a App Secret. As the name says, never make your Secret code public.

Start the authentication

Before you can get access to information of a user, the user needs to give your app permission to access the account. Tho start the authentication process, use the link https://finefriends.social/api/v3/auth?client_id={YOUR_APP_ID}

Once the user clicks the link, the authorization page will be opened. If the user authorizes the app, he/she will be redirected to the Return URL with the GET parameters 'code' and 'state'. Example: https://yourdomain/?code=XXXX&state=XXXX. If the user does not authorize the app, he/she will be redirected to the Return URL with the GET parameter 'error' and value 'access_denied'. Example: https://yourdomain/?error=access_denied

Retreive the information

In the code of your Return URL page, you will need to generate an access token to retrieve the authorized user info. Please use the code below:

<?php
$url_gettoken = 'https://finefriends.social/api/v3/access_token'; //Do not change this URL
$data_gettoken = array(
    "client_id" => "YOUR_APP_ID", //Your application id
    "client_secret" => "YOUR_APP_SECRET", //Your application secret
    "code" => $_GET["code"], //The GET parameter you got in the callback
    "state" => $_GET["state"], //The GET parameter you got in the callback
    "grant_type" => "authorization_code", //Do not change this
);

$ch_gettoken = curl_init($url_gettoken);
curl_setopt($ch_gettoken, CURLOPT_POST, true);
curl_setopt($ch_gettoken, CURLOPT_POSTFIELDS, $data_gettoken);
curl_setopt($ch_gettoken, CURLOPT_RETURNTRANSFER, true);

$payload = curl_exec($ch_gettoken);

$json = json_decode($payload, true);
if(!empty($json['access_token'])){
    $access_token = $json['access_token'];
}
?>

This code will create a one-time access token and get the information from FineFriends.

Using this access code, you can get the data that you would like to retreive.

<?php
$url_getinfo = 'https://finefriends.social/api/v3/user_info'; //Do not change this URL
$ch_getinfo = curl_init($url_getinfo);
curl_setopt($ch_getinfo, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch_getinfo, CURLOPT_HTTPHEADER, array(
    'header' => "Authorization: Bearer ".$access_token, //Set the access token you received as the authorization header.
));
$data = json_decode(curl_exec($ch_getinfo), true);
?>

Use the information

The information returned by the API is formatted in JSON. It looks like this:

{
 "api_status":"success",
 "api_version":"3.1",
 "user_data":{
    "id":"{ID of the user}",
    "name":"{Display name of the user}",
    "email":"{Email address of the user}",
    "username":"{Username of the user}"
 }
}

To use this information, you use the json variable in the code above. For example, if you want to use the users email address, you can use the following snippet:

$data['user_data']['email'];

For testing, you could use the following code. It shows the name, username and password of the FineFriends account.

echo 'Hello, '.$data['user_data']['name'].'. Your username is '.$data['user_data']['username'].' and your email address is '.$data['user_data']['email'];

How to implement the API

You can implement the FineFriends API with your own application. For example, you can use it to let your users sign in using their FineFriends account.

If you want to use FineFriends to let your users sign in, you will need to add an extra column to your databse where you store the user id of the FineFriends account. You cannot use the username or email address to identify a user, since these might change. As long as a user has a FineFriends account, the id stays the same. If you want to create a new account using this method, you can use the email address, display name and username, but you still need to use the user id to identify the FineFriends account. Never use the FineFriends user id as the user id for the accounts your own application.

How do I manage my apps?

You can manage your apps on this page.

Debugging and error handling

If you do not get the expected results, we offer some debugging. If an error occured during the authentication, the response will look like this:

{
 "api_status":"error",
 "api_version":"3.1",
 "error":"invalid_client"
 "error_description":"No client id given!"
}

Every error that occures within the API will be marked using api_status error. The value for error indicates the general error that occured and the error_description gives a human-readable explanation for what went wrong.

To implement error handling, you can use the following code for checking the token response:

if($json['api_status']=="success"){
 //Get info here
} else {
 //Do your error handling here
 //Uncomment following 2 lines to echo the error message
 //echo $json['error'];
 //echo $json['error_description'];
}

And this code for checking the data response:

if($data['api_status']=="success"){
 //Do your magic here
} else {
 //Do your error handling here
 //Uncomment following 2 lines to echo the error message
 //echo $data['error'];
 //echo $data['error_description'];
}


If the user does not authorize the app, he/she will be redirected to the Return URL with the GET parameter 'error' and value 'access_denied'. Example: https://yourdomain/?error=access_denied. You should include a check on the return URL page to detect when the user has denied access.

if(isset($_GET['error'])&&$_GET['error']=='access_denied'){
 //Inform user that access has been denied.
} else {
 //Rest of the code
}