Introduction

An API integration is a technical user that an external system, such as an accounting or treasury application, uses to call the FinologeeBKO API. Each API integration has a name, a generated ID, a secret key, and its own set of permissions. The external system authenticates with the ID and the secret key and can perform only the actions that the permissions of the integration allow.

The API integrations page in tenant settings enables administrators to create and manage API integrations themselves, without contacting Finologee Customer Support. Administrators create integrations, rename them, regenerate secret keys, change permissions, and deactivate or reactivate integrations, and every action appears in an audit log.

API integrations do not appear in the users list of Users & groups. FinologeeBKO also hides its own platform user from the API integrations page.

---

Prerequisites

Access to the API integrations page depends on the tenant settings permissions of the user.

Permissions

📘

Tenant settings approval workflow

When the tenant uses the tenant settings approval workflow, changes to API integrations follow the four-eyes principle. See Approval workflow for API integrations.

---

API integrations list

To open the list, select API integrations in the tenant settings menu. The list shows the following columns:

Users can search by name and ID, filter by Name, Status, and Permissions, sort by name and status, and use the column and view features that other tables offer. Users with TENANT_SETTINGS_WRITE also see the Rename, Deactivate, and Reactivate actions in the row menu, and a bulk Deactivate action for selected integrations.

---

Creating an API integration

Creating an API integration gives an external system its own identity, so administrators can limit what the system can do and switch it off independently of other integrations. The secret key is displayed once at creation, and FinologeeBKO does not keep a readable copy.

To create an API integration:

1. Navigate to API integrations in tenant settings
2. Click Create
3. Enter the name of the API integration
4. Select at least one permission for the integration, using the same permission options as for a user. Users can add and remove permissions before they continue
5. Click Create
6. In the API integration created window, copy the secret key with the copy button or click Download
7. Click Close

The window shows the name, the ID, and the secret key of the integration, with the warning that the secret key cannot be displayed again. The new integration has the status Active.

When the tenant does not use the approval workflow, the integration works immediately, and a confirmation message links to the integration details page. When the tenant uses the approval workflow, the integration becomes usable only after an approver approves the change, and the confirmation message links to pending changes. The secret key that the user copies stays the key of the integration after approval.

⚠️

Keep the secret key safe

If a user closes the window without copying the secret key, the user must regenerate the key to obtain a new one.

---

API integration details

Click an API integration in the list to open its details page. Users with TENANT_SETTINGS_READ or USER_AND_GROUP_READ see the following sections:

• Details — the name and the ID of the integration, with the status in the page header
• Secret key — the masked secret key, with the Regenerate action for active integrations
• Access & permissions — the permissions of the integration
• Audit log — every action performed on the integration

---

Managing an API integration

Renaming an API integration

Renaming keeps the name in line with the purpose of the integration. The ID and the secret key do not change.

1. Open the API integration details page or the row menu in the list
2. Click Rename
3. Enter the new name. The Save button stays disabled until the name changes. The name must be unique among API integrations
4. Click Save

Regenerating the secret key

Regenerate the secret key when a key is lost or may be exposed. The previous key stops working immediately, and the integration uses the new key.

1. Open the details page of an Active API integration
2. In the Secret key section, click Regenerate
3. Confirm the action
4. Copy or download the new secret key from the window that opens

📘

No approval for regeneration

The regeneration of a secret key does not go through the approval workflow and applies to the live configuration at once. The Regenerate button does not appear in edit mode and does not appear for deactivated integrations.

Managing permissions

Permissions control what the integration can do through the API. Users with TENANT_SETTINGS_WRITE manage them in the Access & permissions section, in the same way as for a user. Permissions are available for active and deactivated integrations.

• Add — click Add, select the permission and its scope, and save
• Edit — open the row menu of the permission, click Edit, change the scope, and save
• Remove — open the row menu of the permission, click Remove, and confirm
• Remove in bulk — select several permissions, click Remove in the bulk action menu, and confirm. The confirmation message states how many permissions the action affects

An API integration needs at least one permission when you create it.

Deactivating an API integration

A deactivated integration can no longer access the platform. Deactivate an integration when the external system is retired or when you suspect misuse.

1. Open the details page of an Active integration, or use the row menu in the list
2. Click Deactivate
3. Confirm the action

To deactivate several integrations, select them in the list and click Deactivate in the bulk action menu. The action applies only to active integrations in the selection, and FinologeeBKO states how many integrations the action applies to.

Reactivating an API integration

Reactivation gives a deactivated integration access to the platform again. FinologeeBKO generates a new secret key, because the previous key does not work anymore.

1. Open the details page of a Deactivated integration, or use the row menu in the list
2. Click Reactivate
3. Confirm the action
4. Copy or download the new secret key from the window that opens

---

Approval workflow for API integrations

When the tenant uses the tenant settings approval workflow, administrators make changes to API integrations in edit mode. The following changes appear on the Pending changes page and take effect only after approval by another administrator:

• Creation
• Renaming
• Adding, editing, and removing permissions, including bulk removal
• Deactivation
• Reactivation

An approver can approve or discard each change. After approval, the change applies to the live configuration, and a new integration can call the API. The system stores the secret key of a new or reactivated integration in encrypted form until the approval, then deletes the stored copy. The pending changes view shows the changes in the API integrations section. See Pending changes.

---

Audit log

The audit log on the details page records the following events:

• Creation
• Update, including renaming, permission changes, and the regeneration of a secret key
• Deactivation
• Reactivation
• Notifications sent about the integration
• Removal of the integration from a signatory rule

Actions that approvers approved in the approval workflow show the approval. Actions that API integrations perform have no email address as the owner. Click Download in the audit log section to get a PDF report with the API integration information block (name, ID, permissions) followed by the history.

---

Notifications

FinologeeBKO notifies administrators when an API integration is created, reactivated, or updated. Users with TENANT_SETTINGS_READ, USER_AND_GROUP_READ, or TENANT_SETTINGS_APPROVE receive these notifications, and each user configures the channels in the notification preferences. API integrations themselves never receive notifications. See Notifications.

---

Status definitions

---

Best practices

• Create one integration per external system — Separate integrations let you deactivate or rotate the key of one system without affecting others
• Grant the minimum permissions — Assign only the permissions the external system needs, and scope them to the accounts and categories it uses
• Store secret keys in a secure vault — The key is displayed once, so save it in the credential store of the external system
• Rotate secret keys regularly — Regenerate the key on a schedule and when staff with access to the key leave
• Deactivate unused integrations — A deactivated integration cannot call the API, and you can reactivate it later
• Review the audit log — Check the log after changes to confirm who changed an integration and when

---

Related documentation

• Users & groups - User management and access configuration — Permissions for users and groups
• Pending changes - Configuration change management — Approving changes to API integrations
• Permissions - Comprehensive explanation of access control and role-based permissions — Permission types and scoping
• Notifications - Configure notification preferences and channels — Notifications about API integrations
• API - RESTful API for full automation of FinologeeBKO processes — Using the external API

---

Support

For assistance with API integrations, contact [email protected].