Reading time 3min

Kibi API

Automatically translated

Kibi REST API 允许外部应用程序、AI 助手和自动化工具访问 Kibi Connect 数据。通过 API，可以读取和写入内容——从维基页面到新闻帖子，再到任务和日历条目。

#启用 API 访问

REST API 必须先由系统管理员启用。设置位于：

设置 → 集成 → REST API

此处提供以下选项：

  • 启用 REST API

    开启或关闭 API 接口。

  • 限制令牌创建为特定角色

    如果启用，只有具有选定角色的用户才能创建 API 令牌。此外，还可以通过用户个人资料中的“安全”选项卡中的功能访问权限，授权单个用户。

  • 启用 IP 限制

    如果启用，只有指定的 IP 地址才能访问 API。这是一个额外的安全层。

截图：集成下的 API 设置

#创建 API 令牌

每个用户都可以通过自己的用户个人资料创建 API 令牌。导航至：

用户个人资料 → 集成 → 创建新令牌

创建令牌时需要设置：

  • 名称

    描述性名称（例如“AI 代理”、“ERP 集成”、“工作流自动化”）。

  • 权限（Scopes）

    仅选择集成实际需要的权限（最小权限原则）。

  • 过期日期（可选）

    可以可选设置过期日期，之后令牌将自动失效。

截图：带有 Scopes 的令牌创建表单

#安全保存令牌

创建后，令牌值仅显示一次。请立即复制并安全保存（例如在密码管理器中）。如果丢失，必须撤销该令牌并创建新令牌。

截图：创建令牌后——仅显示一次

#可用权限（Scopes）

以下 Scopes 控制 API 令牌对不同区域的访问：

Scope

描述

posts:read

读取已发布的帖子和新闻

posts:write

创建、更新和删除帖子

wiki:read

读取维基页面和文档

wiki:write

创建和更新维基页面

calendar:read

读取日历条目

calendar:write

创建、更新和删除日历条目

groups:read

读取公开群组、成员、帖子和文件

surveys:read

读取调查和结果

tasks:read

读取任务（仅自己的或分配的）

tasks:write

创建和更新任务

users:read

读取公开用户目录（不包含私人数据）

chat:read

读取对话和消息

chat:write

发送消息（用于机器人和自动化）

notifications:read

读取用户通知

notifications:write

向用户发送通知（包括推送）

search

跨实体搜索

#API 认证

所有 API 请求必须在 Authorization 头中以 Bearer 令牌的形式发送令牌：

curl -H "Authorization: Bearer kbc_IhrTokenHier" \
     https://ihre-firma.kibi.de/api/v1/wiki

API 基础 URL 为：https://ihre-firma.kibi.de/api/v1

#可用端点

完整的 API 文档（包含所有端点和参数）可在 Kibi Connect 中直接查看：

  • 交互式文档：用户个人资料 → 集成 → API 文档

  • OpenAPI 规范（JSON）：用户个人资料 → 集成 → OpenAPI JSON

主要端点概览：

区域

端点

描述

维基

GET /wiki

列出维基页面

维基

POST /wiki

创建维基页面

新闻

GET /posts

列出帖子

任务

GET /tasks

列出任务

日历

GET /calendar/events

列出日历条目

聊天

POST /chat/direct

发送私信

用户

GET /users

列出用户目录

搜索

GET /search

跨实体全文搜索

#管理令牌

所有创建的令牌都会在用户个人资料 → 集成下的概览中显示。此处可以查看：

  • 令牌名称

  • 分配的权限

  • 令牌最后使用时间

  • 撤销令牌的选项

截图：活跃令牌概览

#重要说明

  • 数据访问：API 令牌仅能访问相应用户有权访问的数据。用户的权限仍然适用。

  • 安全性：永远不要公开分享 API 令牌。将令牌存储在环境变量或密钥管理器中，而不是在源代码中。

  • 最小权限：仅授予最低必要权限。用于维基集成的令牌不需要访问聊天。

  • 过期日期：对于临时集成，设置过期日期以提高安全性。

  • 撤销：通过令牌概览立即撤销不再需要的令牌。