# How to Create OAuth Credentials for FreshBooks

This guide will help you set up your FreshBooks OAuth app to connect with Apideck and start using the Accounting API.

> **Do you need your own OAuth app?** For production, yes. Apideck's temporary shared test credentials let you enable the connector and authorize FreshBooks immediately, so you can evaluate the integration before registering anything: on that path the FreshBooks consent screen shows **Apideck** rather than your own brand, which is why it is for testing only. Production connections use your own FreshBooks OAuth app, which puts your own company name and logo on the consent screen and gives you control over the exact scope set your customers approve. To evaluate first, complete [section 1](#1-enable-the-freshbooks-connector-in-apideck) and then skip to [section 4](#4-test-your-connection), and come back here when you are ready to go live.

## Prerequisites

Before you begin, make sure you have:

1. **A FreshBooks account** (trial or paid) - Sign up at [FreshBooks](https://www.freshbooks.com/signup)
2. Access to the [FreshBooks Developer Hub](https://www.freshbooks.com/developers), where **Create an App** opens the developer dashboard at [my.freshbooks.com/#/developer](https://my.freshbooks.com/#/developer)
3. An Apideck account

No paid partnership, revenue-share agreement, or minimum customer count is required: any FreshBooks account holder can register an app and start making live API calls with it straight away.

## 1. Enable the FreshBooks connector in Apideck

1. Navigate to the [Apideck Dashboard](https://platform.apideck.com)
2. Go to **Configuration** > **Accounting** > **FreshBooks**
3. The connector will be available for configuration

## 2. Create OAuth App in FreshBooks Developer Portal

### Access Developer Portal

1. Log in to your FreshBooks account
2. Navigate to the [FreshBooks Developer Hub](https://www.freshbooks.com/developers)

![FreshBooks - Developer Portal](https://res.cloudinary.com/apideck/image/upload/v1767616411/docs/connectors/freshbooks/freshbooks-developer-hub.png)

3. Click **Create an App** or **Get Started** to begin creating your OAuth application

### Configure Basic Information

Fill out the basic information about your OAuth app in the following order:

1. **Application Name**: Enter a descriptive name for your app (e.g., "Apideck Integration")

2. **App Type**: Select the type of app you want to create:
   - **Test App**: For testing and development purposes
   - **Private App**: For internal use within your organization
   - **Public App**: For listing on the [FreshBooks AppStore](https://appstore.freshbooks.com) so that any FreshBooks user can find and install it. A public listing is submitted from the **AppStore Listing** tab on your app and goes through a free, self-serve App Review; the AppStore team follows up by email after submission. **App Review only gates the public listing, not API access** - your app can make live API calls from the moment it is created, in any app type.


3. **Website URL**: Enter your application's website URL (optional but recommended)

4. **Application Settings URL**: Enter the URL where users can manage your app's settings, for example: https://vault.apideck.com (optional)


![FreshBooks - Basic Information](https://res.cloudinary.com/apideck/image/upload/v1767616411/docs/connectors/freshbooks/freshbooks-create-application.png)

5. **Scopes**: Select the OAuth scopes that match the resources you need to access through the FreshBooks API. FreshBooks defines 44 scopes across 24 objects: a read scope and, for most objects, a matching write scope. Four objects are read-only and have no write counterpart (`user:profile:read`, `user:business:read`, `user:notifications:read` and `user:reports:read`). Grant only the ones your integration actually uses. The scopes behind the Apideck accounting resources are:
   - `user:profile:read` - View personal and business details. This is a default scope granted to every app and cannot be removed.
   - `user:clients:read` / `user:clients:write` - Access client information
   - `user:invoices:read` / `user:invoices:write` - Access invoice data
   - `user:payments:read` / `user:payments:write` - Access payment information
   - `user:account:read` / `user:account:write` - Access chart of accounts (ledger accounts)
   - `user:billable_items:read` / `user:billable_items:write` - Access invoice items
   - `user:bills:read` / `user:bills:write`, `user:bill_payments:read` / `:write`, `user:bill_vendors:read` / `:write` - Access bills, bill payments and vendors
   - `user:credit_notes:read` / `:write`, `user:journal_entries:read` / `:write`, `user:taxes:read` / `:write` - Access credit notes, journal entries and tax rates
   - `user:reports:read` - Read the balance sheet and profit and loss reports


6. **Redirect URI**: Enter **exactly** `https://unify.apideck.com/vault/callback`

   Three FreshBooks rules to keep in mind for this field:
   - The URI must be **HTTPS**. FreshBooks only accepts plain HTTP for local development.
   - The URI must **not contain query-string parameters**. If you need to carry your own data through the authorization flow, use the OAuth `state` parameter instead.
   - An app can hold **multiple redirect URIs**, so adding the Apideck callback does not replace one you already use elsewhere.


![FreshBooks - Basic Information](https://res.cloudinary.com/apideck/image/upload/v1767616410/docs/connectors/freshbooks/freshbooks-redirect-uri.png)

### Get Your Credentials

After creating your app, FreshBooks will generate your OAuth credentials:

- **Client ID** - This is your application's public identifier
- **Client Secret** - This is your application's secret key

![FreshBooks - Copy Credentials](https://res.cloudinary.com/apideck/image/upload/v1767616410/docs/connectors/freshbooks/freshbooks-copy-credentials.png)

### Grant type and token lifetimes

FreshBooks supports the **Authorization Code** grant only. The `client_credentials` grant is explicitly not supported, so a FreshBooks user always has to approve the connection interactively; there is no machine-to-machine alternative.

| Credential | Lifetime |
|---|---|
| Authorization code | 5 minutes |
| Access token | 43,200 seconds (12 hours) |
| Refresh token | No expiry of its own, but **single use** - every refresh issues a new refresh token and invalidates the previous one |

Apideck Vault performs the refresh and stores the rotated refresh token, so your application does not have to manage this cycle. Because only one refresh token is valid per user per app at a time, avoid refreshing the same FreshBooks grant from another system alongside Apideck: whichever side refreshes last invalidates the other side's token and the consumer will have to reauthorize.


## 3. Configure the FreshBooks connector in Apideck

1. Navigate to the [FreshBooks connector configuration](https://platform.apideck.com/configuration/accounting/freshbooks) in the Apideck Dashboard
2. Select the **Use your own client credentials** option
3. Enter your OAuth credentials:
   - **Client ID** - Paste the Client ID from your FreshBooks Developer Portal app
   - **Client Secret** - Paste the Client Secret from your FreshBooks Developer Portal app
4. Review that the scopes granted in FreshBooks match with the scopes you are requesting in Apideck
5. Click **Save settings** to save your credentials

![Apideck - Configure FreshBooks connector](https://res.cloudinary.com/apideck/image/upload/v1767616410/docs/connectors/freshbooks/apideck-configuration-connector.png)

## 4. Test Your Connection

You can test your FreshBooks connector by clicking **Test Vault** in the Apideck dashboard.

1. Click **Authorize** to start the OAuth flow

![FreshBooks - Unauthorized Connection](https://res.cloudinary.com/apideck/image/upload/v1767616410/docs/connectors/freshbooks/apideck-unauthorized.png)

2. You'll be redirected to FreshBooks to grant permissions
3. Select the business/account you want to connect from the dropdown list (you must have owner or admin role)
4. After successful authorization, the connection will show as **Connected**


![FreshBooks - Authorized Connection](https://res.cloudinary.com/apideck/image/upload/v1767616410/docs/connectors/freshbooks/apideck-connected.png)


## 5. Do your first API call to the Accounting API

1. Connect through [Vault](https://platform.apideck.com/vault)
2. Test with this call:

```bash
curl --location 'https://unify.apideck.com/accounting/customers' \
 --header 'x-apideck-consumer-id: test-consumer' \
 --header 'x-apideck-app-id: {APIDECK_APP_ID}' \
 --header 'x-apideck-service-id: freshbooks' \
 --header 'Authorization: Bearer {APIDECK_API_KEY}'
```

## FAQ and troubleshooting

**The authorization fails with a redirect URI error.** The value in your FreshBooks app must match `https://unify.apideck.com/vault/callback` character for character, must be HTTPS, and must carry no query-string parameters.

**Authorization fails with `invalid_grant`.** An authorization code is valid for 5 minutes and can only be exchanged once. Start the **Authorize** flow again rather than retrying the old code.

**A working connection suddenly needs reauthorizing.** FreshBooks refresh tokens are single use and only one is valid per user per app. If the same FreshBooks grant is also refreshed outside Apideck, the stored token is invalidated and the consumer has to reconnect.

**A resource returns 403 or comes back empty after you add a scope.** FreshBooks does not extend consent that has already been given: grants issued before you added the scope keep the older, narrower scope set. Existing consumers must reauthorize the connection before the new scope takes effect.

**The consumer cannot select their business during authorization.** Selecting a FreshBooks business requires the **owner** or **admin** role on that business. A user with a lower role can authorize the app but will not be offered the business they expect.

**Where to get help.** For Apideck configuration questions, contact [Apideck Support](https://help.apideck.com/en/articles/7774658). For questions about your FreshBooks app, its scopes, or App Review, use the support contact listed on the [FreshBooks Developer Hub](https://www.freshbooks.com/developers).

---
Now your app and FreshBooks integration are configured! 🎉