Guides
Start typing to search…

Getting started with Public Integrations

This guide will help you get started with vendor integrations (Public Integrations) for the Bokio API.

🚧

Functionality in development

The content in this section or page is currently under development and is not yet available. The functionality may also undergo significant changes.

By providing the API as a beta we hope to be able to iterate quickly based on feedback. Please reach out to [email protected] or join the Developer community. We appreciate any feedback you might have.


For Public Integrations the workflow for getting setup is:

  • Sign up for a Bokio developer account and integration
  • Create an integration
  • Copy client id and client secret
  • Make API token request
  • Make an API request

Step 1: Sign up for a Bokio developer account and integration

To access the Bokio API, you need to sign up for a developer account and create an integration. At this early stage the developer accounts are created upon requests to Bokio after discussion on the integration you want to build.

Step 2: Copy client_id and client_secret

With the integration created we will share client_id and client_secret through one-time links. These will later be used to authenticate using the OAuth grants. Make sure to store these values securely and avoid keeping them on local machines.

❗It's critical that you store integration secrets securely. Do not keep secret on local files or in source control. If you suspect a secret could have been accessed illegitimately, please revoke the secret in the developer portal.

Step 3: Accessing the General API

With the client_id and client_secret it's possible to retrieve tokens for the General API through the Client Credentials Grant.

GET https://api.bokio.se/token HTTP 1.1
Authorization: Basic Base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=client_credentials

Now we can start making request to the General API. For example, checking connections for our app.

GET https://api.bokio.se/connections HTTP 1.1
Accept: application/json
Authorization: Bearer NbV3MZS7R1ApJwTyHq8XkLf4PGd9OuE5CiQn2BgKrDzFvYm

Step 4: Accessing the Company API

The Company API contains all operations that can be done through the API on behalf of a Company tenant. Each access token is restricted to one tenant.

Start by having the user agent navigate in a browser to Bokio using a request similar to:

GET https://api.bokio.se/authorize?client_id=ed56c798-0ac8-4700-abd9-3dac99f7eca1&redirect_uri=https%3A%2F%2Fhost%2Fcallback&scope=accounting%20invoices&state=somerandomvalue&response_type=code HTTP 1.1

302 https://host/callback?code=id2-4IE6ACIT5yIMB2ae5zVV4PrisE5-8q_ehKfezK4&state=somerandomvalue HTTP 1.1

⚠️

Validate state parameter

Please not that before proceeding you must validate the state parameter. By doing so you help users avoid CSRF (Client Side Request Forgery) attacks.

Not that you have the code you can make a request to retrieve the access_token and refresh_token.

POST https://api.bokio.se/token HTTP 1.1
Authorization: Basic Base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=code&code=id2-4IE6ACIT5yIMB2ae5zVV4PrisE5-8q_ehKfezK4

If the request is successful the response will contain a json similar to the one below.

{
  "tenant_id": "1be29990-f977-4a62-bb03-f0e126e685d0",
  "tenant_type": "company",
  "access_token": "tffNhGDZ1FCpEWMkHduTA9FBnvNptzWSUfIlbcBHpdG5YJL",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "RpV4TYS8Z1KnJHpAqPJzXtl5QDl6OuK6NrQJk2FfLrGzKiM"
}

Now we can start working with company data. For example by doing the following request:

GET https://api.bokio.se/companies/1be29990-f977-4a62-bb03-f0e126e685d0/journal-entries?page=1&pageSize=50 HTTP 1.1
Accept: application/json
Authorization: Bearer tffNhGDZ1FCpEWMkHduTA9FBnvNptzWSUfIlbcBHpdG5YJL

Updated 13 days ago