Introduction to Agency API

What is an agency in Bokio?
An agency is an accounting practice that manages bookkeeping and related work for multiple client companies in Bokio. Each agency is an independent Bokio tenant with its own agency ID. Companies managed by the agency keep their own company IDs and data.

What is the Agency API?
The Agency API exposes operations for integrating an accounting practice with Bokio. It lets an integration work across an agency and its client companies—for example, to list or create client companies, manage users and invitations, retrieve worklists, and generate links that open a company in Bokio.

All Agency API endpoints use the base URL:

https://api.bokio.se/v1

Most endpoints that operate on a connected agency are located under:

https://api.bokio.se/v1/agencies/{agencyId}/

The agencyId identifies the agency, while a companyId identifies one of its client companies. Do not use a connection ID or integration ID in place of either tenant ID.

Connecting an integration to an agency

The Agency API supports two connection models. The model available to your integration depends on how it has been registered and approved by Bokio.

Authorization Code flow

Use the OAuth 2.0 Authorization Code flow when an agency user should explicitly select an agency and consent to the integration's access.

1. Redirect the user to https://api.bokio.se/v1/authorize.
2. Include bokio_tenanttype=agency, your registered client_id and redirect_uri, the requested agency scopes, response_type=code, and a cryptographically random state value.
3. Validate state when Bokio redirects back to your application.
4. Exchange the authorization code at https://api.bokio.se/v1/token. Authenticate the client with HTTP Basic authentication using the client ID and client secret.
5. Store the returned access_token, refresh_token, tenant_id, and connection_id securely.

For an agency authorization, tenant_id is the Bokio agency ID. Use this value as {agencyId} in Agency API paths. One agency connection covers the agency and all client companies managed through it; separate OAuth connections are not required for each company.

Access tokens expire. Use the refresh token to obtain a new access token, and store the rotated refresh token returned by Bokio. If an agency disconnects the integration, subsequent requests will no longer be authorized and the agency must reconnect.

Client Credentials flow

Approved machine-to-machine integrations can use the OAuth 2.0 Client Credentials flow without an interactive agency user. This capability requires explicit approval by Bokio.

1. Request a token from https://api.bokio.se/v1/token using grant_type=client_credentials, the required Agency API scopes, and HTTP Basic client authentication.
2. Find the agency by exact organization number using GET /agency-information.
3. Connect the integration using POST /agency-connections and the returned agency ID.
4. Use the agency ID in subsequent /agencies/{agencyId}/... requests.

A Client Credentials token is not tied to one agency when it is issued. Agency access starts only after the integration creates an agency connection. The connection records the approved scopes and isolates each integration's access. Repeating the connect request for an existing connection updates it to the scopes requested by the integration.

Revoking the machine-to-machine privilege disconnects the integration's active agency connections. Disconnecting an agency removes the integration's access but does not delete the agency or its companies.

What can the Agency API do in Bokio?

Agency information

Agency information identifies an accounting practice by its Bokio agency ID, name, and organization number.

Connected integrations can retrieve information for an agency. Approved machine-to-machine integrations can also resolve an exact organization number using GET /agency-information. Partial organization-number and name searches are not supported.

Agency connections

Agency connection endpoints are used by approved machine-to-machine integrations to connect to and disconnect from agencies.

An integration can create a connection, list its active connections, retrieve a specific connection, or disconnect from an agency. Connection records include the agency, status, scopes, and connection date. An integration can only see and manage its own connections.

Client companies

A client company is a Bokio company managed by an agency. Each company has its own company ID and remains an independent tenant.

The client-company endpoints allow an integration to list and retrieve companies managed by an agency. An integration can also create a new company and connect it to the agency. When creating a company, the owner email must belong to an existing Bokio user who is already a member of the agency.

Use the id returned by the client-company endpoints as {companyId}. The company ID is not the same as an agency-company relationship ID.

Agency and company users

The user endpoints allow an integration to list and retrieve agency users and users of a specific client company. They also allow authorized integrations to remove users, subject to Bokio's ownership and membership rules.

User responses contain the Bokio user ID, email address, display name, and status. The Bokio user ID is required by operations that act on behalf of a particular user, such as retrieving that user's to-dos or generating a company navigation URL.

Invitations

Invitations are exposed through dedicated endpoints for the agency and for each client company. An integration can list pending invitations and invite a user by email.

Agency invitations add accounting-practice staff. Company invitations add a user to a particular client company. A pending invitation has its own invitation ID and is not interchangeable with an active Bokio user ID.

Company to-dos

The to-do endpoint returns the current worklist for a specific user in a client company managed by the agency. To-dos can represent work such as recording a receipt, paying a supplier invoice, or receiving payment for an invoice.

The request path contains the agency ID, company ID, and Bokio user ID:

GET /agencies/{agencyId}/companies/{companyId}/users/USERID/todos

Use the Accept-Language header with sv or en to select the language of localized to-do titles. If the header is omitted or unsupported, Bokio uses Swedish. The selected language is returned in the Content-Language response header.

Navigation to a client company

The navigation endpoint generates a deep link that opens a client company in Bokio. It can be used for a Go to Bokio action in an agency portal.

GET /agencies/{agencyId}/companies/{companyId}/navigation?userId=USERID

The userId query parameter is required and must identify the Bokio user who will open the company. That user must be a member of the client company. You can obtain the user ID from:

GET /agencies/{agencyId}/companies/{companyId}/users

An optional todoType query parameter can direct the user to a specific area in Bokio.

The response contains a URL. Redirect the user's browser to that URL; do not treat it as an API resource to fetch from your backend.

Scopes

Agency API permissions are controlled with OAuth scopes. Common scopes include:

• agency-information:read — read or resolve agency information
• agency-connections:read — list the integration's agency connections
• agency-connections:write — connect to or disconnect from agencies
• agency-companies:read — read client companies and generate company navigation links
• agency-companies:write — create and manage client companies
• agency-users:read — read agency users, company users, and invitations
• agency-users:write — invite or remove users
• agency-todos:read — read company worklists for users

Request the smallest set of scopes required for your use case. A scope in an access token does not override agency membership, company membership, connection ownership, or other authorization checks.

Pagination, filtering, and errors

List endpoints are paginated. Use page and pageSize; the maximum page size is 100. Endpoints that support query use Bokio's filtering syntax. Always URL-encode filter expressions.

Bokio API errors normally include:

• code — a stable machine-readable error code
• message — a human-readable explanation
• bokioErrorId — an identifier to include when contacting Bokio support

Handle authorization failures and disconnections explicitly. A 401 generally means the token or connection is no longer valid. A 403 means the caller is authenticated but does not have the required scope, connection, privilege, or membership. A structured 404 means the requested resource is not available within the connected agency context.