API Reference
Start typing to search…

Authentication for Public Integrations (OAuth)

To access the Bokio API with a Public Integration, you need to pass an access token that can be obtained through OAuth 2.0. Depending on the APIs to access, different OAuth 2.0 grants are used.

📘

Modifications to OAuth 2.0 (RFC 6749)

The Bokio API requires the state parameter to be included in the authorization request.

Public Integrations needs to be registered to obtain the client_id and client_secret. To run the OAuth 2.0 Authorization Code Grant for Company API the registration must include the redirect_uri to be in the /authorize request.

Using OAuth 2.0 Authorization Code Grant for Company API

To access the Company API with Public Integrations you need to pass an access token that can be obtained through OAuth 2.0 Authorization Code Grant.

Obtaining the Access Token

Start by redirecting the user to the authorization endpoint.

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

The user will be redirected to Bokio to log in and grant permission to the application. Bokio will then redirect the user back to the application with an authorization code.

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.

Using the authorization code, you can exchange it for an access 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

The access token returned is a JSON object that contains the following information:

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

Now the access token can be used to make requests to the Bokio API.

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 access_token_from_token_request

When the access token expires, you can use the refresh token to get a new access 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=refresh_token&refresh_token=RpV4TYS8Z1KnJHpAqPJzXtl5QDl6OuK6NrQJk2FfLrGzKiM

A new access token is returned.

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

Using OAuth 2.0 Client Credentials Grant for General API

To access the General API with Public Integrations you need to pass an access token that can be obtained through OAuth 2.0 Client Credentials Grant.

Obtaining the Access Token

Start by making a request to the token endpoint with grant_type=client_credentials

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

The access token returned is a JSON object that contains the following information:

{
  "tenant_id": "",
  "tenant_type": "general",
  "access_token": "NbV3MZS7R1ApJwTyHq8XkLf4PGd9OuE5CiQn2BgKrDzFvYm",
  "token_type": "bearer",
  "expires_in": 3600,
}

Note that the tenant_id is empty and tenant_type is set to General. There is no refresh token provided, a new access token can be obtained by making a new request to the token endpoint with grant_type=client_credentials.

Now the access token can be used to make requests to the Bokio API.

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

Handling Authentication Errors

If you make a request without a valid Integration token or with an expired Integration token, you will receive a 401 Unauthorized response.