Looking for your bookmarks? You can find them on this page
This takes longer than usual...
FineFriends for Developers
By using FineFriends, you agree to our cookie policy.

API

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

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

Getting started (V3)

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.nl/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: http://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: http://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.nl/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.nl/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.0",
 "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.0",
 "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: http://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
}

Getting started (V2)

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.nl/api/auth/{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 'token'. Example: http://yourdomain/?code=XXXX&token=XXXX. If the user does not authorize the app, he/she will be taken to your Public URL.


Retreive the information

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

<?php
$app_id = 'YOUR_APP_ID'; // your application app id
$app_secret = 'YOUR_APP_SECRET'; //your application app secret
$code = $_GET['code']; // the GET parameter you got in the callback: http://yourdomain/?code=XXX
$access_token = $_GET['token']; // your access token
$type = "get_user_data"; // What to get from the api

$get = file_get_contents("https://finefriends.nl/api/app_api?token={$access_token}&code={$code}&app_id={$app_id}&secret={$app_secret}");

$json = json_decode($get);
?>

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


Use the information

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

{
 "api_status":"success",
 "api_version":"2.0",
 "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:

$json->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 row 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":"2.0",
 "api_error":"No App Secret given!"
}

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

if($json->api_status=="success"){
 //Do your login magic here
} else {
 //Do your error handling here
 //Uncomment following line to echo the error message
 //echo $json->api_error;
}