Kashoo API Documentation (1.0.0)

The API reference lists all available endpoints for products Kashoo Cloud Accounting and TrulySmall Accounting. The endpoints are divided topically and have references on the product to make it easier for you to navigate through the docs.

A Kashoo or 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 application 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. When developing an api client, you may ask to be put on a free subscription plan so that your business and its data stay accessible over the course of your development.

Product identification markers

This API supports two of our products: Kashoo Cloud Accounting and TrulySmall Accounting. You can sign up for either application at https://kashoo.com/. The API for the two products is essentially the same with a couple important differences:

• TSA supports opening balances for accounts while Kashoo has to do this with adjustments.
• The tax system is different between the two products. The TSA tax system is more structured and constrained.
• TSA supports a shoebox items api for staging transactions before they are posted to the ledger.
• Kashoo supports basic inventory items while TSA does not.

The API endpoints indicate which of our products they are meant for using one or both of the following product markers.

kashooKashoo Cloud Accounting (Our classic platform) tsaTrulySmall Accounting (Our leading-edge platform)

Note that the applicatinos are hosted under different domains. This is mostly cosmetic, since they map to the same backend, but is worth following. The Kashoo api is hosted at https://app.kashoo.com/api while the TSA api is at https://app.trulysmall.com/api.

Kashoo allows for two categories of authentication: first-party and third-party. First-party authentication is simple but meant for first-party development since it requires the user's password. Third-party authentication is for external developers who wish to integrate with TrulySmall, but it takes more time to get running.

First-party Authentication

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

The endpoints for first-party authentication are under the /authTokens path. See the ebdpoints below for more information.

When a first-party login completes successfully, the api returns a json token. For example, a login call to POST https://api.kashoo.com/authTokens with an accept header of json will return the following:

{
"authenticationCode":"asdasdasdasdasdadasdasdasda",
"expiryDate":1698789858551,
"locale":"default",
"myUserId":1231232,
"restriction":null,
"site":"app.kashoo.com"
}

This json can then be used within Authorization headers using the format:

Authorization: TOKEN json:{"authenticationCode":"asdasdasdasdasdadasdasdasda","expiryDate":1698789858551,"locale":"default","myUserId":1231232,"restriction":null,"site":"app.kashoo.com"}

These tokens are valid for a limited but relatively long time. Once they expire, the user must log in again.

First-party login requires the user to enter their password, which is not suitable for third-parties since the password should only be shared with Kashoo. For this purpose, Kashoo provides an OAuth2 service that allows third-parties to redirect users to Kashoo to log in and then redirects them back to the third party app with an auth code that can be exchanged for an access token. The third party can then use the access token to make api calls to Kashoo on the user's behalf.

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 Kashoo. This is done manually and requires contacting Kashoo to provide the application's name and its redirect URLs for the OAuth2 flow. Note that there currently can only be one redirect url per client id. Once the app is registered, the developer will receive their client id and secret to use in the OAuth2 flow.

Here is a brief outline of the flow:

1. A single page app (SPA) redirects the browser/user to the Kashoo OAuth2 authorization endpoint.

   // client side code
   
   // generate a random state token to prevent cross-site request forgery
   const state = Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15)
   
   // store the state somewhere to verity it upon the response (this part is simplified here)
   sessionStorage.setItem('sign-in-state', state)
   
   window.location.href = 'https://app.kashoo.com/oauth2/authorize?' +
      'client_id=' + yourClientId +
      '&response_type=code' +
      '&scope=full-access' +
      '&redirect_uri=' + encodeURIComponent(yourRedirectUrl) +
      '&state=' + state
   

2. The user logs in to Kashoo on the OAuth2 application and is sent 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 Kashoo.

   // 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', yourRedirectUrl)
   
   // make a call to the OAuth2 server to exchange the code for an access token using form encoded data
   // and the client id and secret as a basic-auth Authorization header
   axios.post('https://app.kashoo.com/oauth2/token', formData, {
       headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
           auth: {
           username: yourClientId,
           password: yourClientSecret
       }
   })
   .then(response => {
           // parse the response data into tokens and user id
           this.bearerToken = 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 store the bearer and refresh tokens for the user and use them to make api calls to Kashoo.

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 only sms as a second factor at this time.

kashootsaContains endpoints to manage users, groups, and roles in a business.

kashootsa

kashootsa

kashootsa

kashootsa