Social Login

Social Login provides the following benefits:

1. Authenticate all identities who are already logged in to their FreshBooks account with a single click.
2. Reduce your development costs by avoiding the need to build your own authentication system.
3. Avoid managing multiple email and passwords for the same identity by reusing the login credentials stored in FreshBooks.
4. Ensure your authentication process remains secure by allowing us to stay on top of the latest security best practices on your behalf.

Overview

To get started, you will need to create a FreshBooks app. If you have already created an app, you can already leverage FreshBooks’ Social Login by making use of your Authentication URL.

The Authentication URL is normally used to retrieve access tokens after a visitor has entered their FreshBooks email/password and has agreed to “allow” you to access their FreshBooks data. This flow typically occurs only one time when the app is first installed. API developers will often store the access tokens for future use and reserve the Authorization URL for first time installations of their app.

Leveraging FreshBooks Social Login is accomplished by sending an unverified identity to your existing Authorization URL. If valid access tokens are returned, this will serve as proof of their identity. You can redirect your unverified visitor to your Authorization URL from your web app or have them click on an image link. For your convenience, you can make use of the following images for use with your Authorization URL.

Big Button (315px width; 48px height)

Small Button (260px width; 40px height)

Scenario Example:

1. Your visitor’s identity is automatically verified and can be redirected to any resources you want them to access. This outcome occurs when the visitor is already logged into their FreshBooks account.
2. If your visitor is not logged in to their FreshBooks account, they will be prompted to enter their email and password. Upon entering the correct credentials, they are redirected to your desired resource. 
3. If your visitor has never installed your app, they will be prompted to log in to their FreshBooks account and “allow” you to access their FreshBooks identity data. Subsequently, they can be redirected to your desired final destination. This outcome will only occur once and will typically have taken place already.
4. If your visitor does not have a FreshBooks identity, they are welcome to create a new FreshBooks account from the login page before attempting to visit your Authentication URL.

Social Login Example

1. You have setup an app on your developer portal where you have:
   1. Entered:
      1. An App Name: Social Login Example App
      2. A Redirect URL: https://webhook.site/7fa7ae5a-b640-420a-8790-ce30713bfea2
   2. We provide you with the follow:
      1. Client ID: 7ec751f9ffdbde0b474fd930942b2bc2292a477de0b7287a547bb7e57ee10141
      2. Client Secret: fad4ff56a36903dcb3a937d2ec708066513b04c0203c3396fa2u348u34f07937407
      3. Authentication URL
2. A visitor on your web service clicks on your “Log in with FreshBooks” image which directs them to your Authentication URL.
3. If the visitor is already logged into their FreshBooks they are automatically redirected to your Redirect URL with an appended code:
   ?code=459bb633f4d06aff97b30956e6898436cd27692950b4796762261c40809b1091
4. This code is sent to the OAuth URL where an access_token is returned.

curl -L -X POST 'https://api.freshbooks.com/auth/oauth/token' \
-F 'grant_type="authorization_code"' \
-F 'client_id="7ec751f9ffdbde0b474fd930942b2bc2292a477de0b7287a547bb7e57ee10141"' \
-F 'client_secret="fad4ff56a36903dcb3a937d2ec708066513b04c0203c3396fa2u348u34f07937407"' \
-F 'code="6ccc545aecf51e5cbe9fc37da025281bc9e7662a1b7b1b492e67a3aa94b66021"' \
-F 'redirect_uri="https://webhook.site/7fa7ae5a-b640-420a-8790-ce30713bfea2"'

#Response 

{
    "access_token": "eyJraWQiOiJhMTlPSlR5aVlKOXhPM3FoWnhWeE1KZE5ZNXJ4cUhpQzBSTUY0TWRheGtjIiwiYWxnIjoiUlMyNTYifQ.eyJqdGkiOiJiY2U1M2Y0NTNlMTVmNTM5MzJjYTQPwzR2-W1GOmodMQl7Nwtc3Gkc-1gXtPQYFixBrdQg",
    "token_type": "Bearer",
    "expires_in": 43200,
    "refresh_token": "f8cddb919402989a72918f55a8fe31f36f353d409e018781d0f59c44e1e59e03",
    "scope": "user:profile:read user:expenses:read user:expenses:write user:clients:read user:clients:write",
    "created_at": 1646237089,
    "direct_buy_tokens": {}
}

5. The visitor is now authenticated and has proven their ability to access their FreshBooks account. You will likely want to send an API request to the Me Endpoint using the access_token. This will return additional identity information such as the visitor’s name and email.

curl GET -H "Authorization: Bearer <insert-bearer-token>" "https://api.freshbooks.com/auth/api/v1/users/me"

#Response

{"response":{"id":44599,"profile":{"setup_complete":true,"first_name":"API","last_name":"Team","phone_number":null,"address":null,"professions":[{"id":29505,"business_id":21230,"title":"Accounting","company":"API Help","designation":null},..

6. Armed with your visitor information, you can now serve any matching resources stored on your web service.

If you need any additional help or have any follow-up questions, please email us at api@freshbooks.com and we will be happy to assist you further.