TrulySmall API Gateway (0.5.0)

This document describes the TrulySmall Accounting API. This is the api used by the TrulySmall Invoicing, Expenses, and Ledger applications.

The api defines an accounting ledger and the additional features needed by the applications.

A TrulySmall user account is needed to use the api. The quickest way to get started is to sign up for a free trial with one of our applications. This will create an account for you, along with a user and a business. You can then use your credentials to obtain an authentication token and start using the api.

The ledger is centered around businesses, one of which will be created for you when you sign up for an account. Most endpoints accept a business id to identify who the operation is for. For example, a business will have its own contacts, taxes, transactions, accounts, and so on.

To allow for multi-user businesses, a user account is also assigned a user id. The user id can be associated with more than one business. The authentication token will only allow access to the business data for which the user has been granted access to. The user id is also used for user-specific operations such as purging a user account.

Subscriptions are centered around businesses. Each business must pay for its own subscription. A user can access any businesses that they have access to as long as the business is on an active subscription.

API Authorization

TrulySmall allows for two categories of authentication: first-party and third-party. First-party authentication is for developers at TrulySmall who are building apps for the company. Third-party authentication is for external developers who wish to integrate with TrulySmall.

First-party Authentication

There are two ways to log the user in directly: either standard user-password login or through single-sign-on providers such as Google, Apple, or Facebook.

The endpoints for first-party authentication are under the /useraccount path. See that section below for more information.

When a login completes successfully, the api returns a bearer token and a refresh token. The response also includes the user account's user and business information needed for making subsequent calls. For example, a login call to POST /useraccount/login/tse will return the following:

{
"refreshToken": "refresh-token",
"token": "bearer-token",
"user": {
  "id": "95748954-6601-4eba-a230-b302ebb92c07",
  ... other user properties ...
},
"business": {
  "id": "ed7fd001-5330-43ff-9923-31ff9766d9f6",
  ... other business properties ...
}

The returned bearer token must be passed in within the Authorization header for each call, in the format Bearer bearer-token. When the token expires, a 401 response will be given, and the client app can use the refresh token to obtain a new bearer and refresh token. This is done with the call POST /useraccount/tokens/refresh.

Multi-factor Authentication

Users can enable multi-factor authentication (MFA) on their account. When MFA is enabled, the user must use another authentication method in addition to their password to complete their login and receive an authentication token. The api supports authenticator apps, email, and sms as second factor methods.

Third-party Authentication / OAuth

First-party login requires the user to enter their password, but we don't want users sharing their TrulySmall login information with any third parties. Instead, TrulySmall provides an OAuth2 server that allows third-parties to redirect users to TrulySmall to login and then redirects them back to the third party app with an access token. The third party can then use the access token to make api calls to TrulySmall on behalf of the user.

An explanation of OAuth2 is beyond the scope of this document. There are many resources online that explain the protocol, for example this one.

To get started, a third-party developer must register their app with TrulySmall. This is done manually and requires contacting TrulySmall and providing the redirect URLs for the OAuth flow. Once the app is registered, the developer will receive login and logout URLs to initiate the OAuth flow, as well as a client id and secret to use within it.

Here is a brief outline of the flow:

1. A single page app (SPA) redirects the browser/user to the TrulySmall login URL, which includes the client id and the redirect URL as query parameters. The redirect URL must be one of the URLs registered with TrulySmall for the app.

   // client side code
   
   // generate a random CSRF token to prevent cross-site request forgery
   const csrfToken = Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15)
   
   // store the state in the session storage so that we can validate it when we get the response
   sessionStorage.setItem('csrf-token', csrfToken)
   
   window.location.href = 'https://accounts.trulysmall.net/oauth2/authorize?' +
   'client_id=... the client id ...' +
   '&response_type=code' +
   '&scope=offline_access' +
   '&redirect_uri=... the redirect uri ...' +
   '&state=' + csrfToken
   

2. The user logs in to TrulySmall on the OAuth server and is redirected back to the redirect URL with an authorization code.

   https://redirect-uri?code=... the authorization code ...&state=... the state ...

3. The redirect URL should be handled by a server-side handler because it will need the client secret. It will use the authorization code and client secret to obtain an access token from TrulySmall.

   // server side code
   
   // send the following as form data
   let formData = new URLSearchParams()
   formData.append('code', ... received authorization code ...)
   formData.append('grant_type', 'authorization_code')
   formData.append('redirect_uri', ... the redirect uri ...')
   formData.append('client_id', ... the client id ...')
   formData.append('client_secret', ... the client secret ...')
   
   // make an axios call to the oauth server to exchange the code for an access token using form encoded data
   axios.post('https://accounts.trulysmall.com/oauth2/token', formData, { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } })
       .then(response => {
           // parse the response data into token and user id
           this.token = response.data.access_token
           this.refreshToken = response.data.refresh_token
           this.expiresIn = response.data.expires_in
           this.tokenType = response.data.token_type
           this.userId = response.data.userId
   

4. The server-side handler should redirect the browser back to the SPA with the access token, refresh token, and csrf cookie as http-only cookies.

5. The SPA can now make api calls to TrulySmall on behalf of the user by passing the access token in the Authorization header.

OAuth Notes

• This flow and documentation is still a work in progress. We have not had a reason to use it extensively yet, though the oauth server is production ready and tested.
• The tokens currently have full access to the user's account. We will be adding scopes to the tokens in the future.

The api uses several data types that are worth documenting.

IDs

The object ids within the api are generally string version 4 UUIDs, for examplea6f573e7-39fb-4a6c-b010-81127b4ab7f7. The api assigns object ids on creation but the client can also provide them if it's helpful.

Amounts

Amounts are represented as whole number strings, for example "100" as $1.00. The amounts are whole numbers obtained by multiplying the real amounts by the currency base amount (which is 100 for USD). This is done to avoid any floating point arithmetic errors. Amounts are currently represented as strings due to a Google protobuf typing design decision. The api must represent amounts internally as 64-bit integers, but the JavaScript specification only supports 63-bit integers, hence protobuf encodes them as strings.

Currencies

Amounts are always paired with currency codes. These are three-letter codes defined in ISO 4217, for example 'USD'.

Dates and Times

Times are represented as RFC 3339 strings, for example 2021-08-12T12:34:56.789Z. Transactions can either be assigned dates with no time component, or full date-times. (Note that the api documentation shows dates as including a zero time component, but this is ignored by the api.) The date-times include time and timezone components, so they can be in UTC or in the user's local timezone.

Timezones

Transactions also accept timezones along with date-times. These are used to explicitly state where the user is entering the transaction irrespective of the timezone format used within the date-time. Timezones are those defined in the tz database, for example 'America/New_York'.

Enums

The api uses several enums, for example for transaction types and category accounts. These are represented as strings and follow protobuf naming conventions, for example TRANSACTION_TYPE_INCOME.

User account management for TrulySmall apps. Used for registering new users, logging in, and managing user settings.

Endpoints for managing subscriptions for a business. This is the subscription that the business has with TrulySmall and determines whether the business is allowed to use the TrulySmall apps.