Authentik 2026.8 API 使用详解

‍‍‌> 目标：以本机 2026.8.4 实例为基准，讲清 /api/v3 的认证方式、通用约定与 users/applications/flows/outposts 四个核心域的 CRUD 用法，全部请求与响应均为实测照抄。

一、环境信息

操作系统：Ubuntu 22.04（x86_64）
Authentik 版本：2026.8.4（GET /api/v3/admin/version/ 实测）
API 基址：http://localhost:13904/api/v3
Schema：OpenAPI 3.0.3（GET /api/v3/schema/ 实测返回 YAML，默认 Accept 即可；含 607 条路径）
实测时间：2026-10-18
客户端：curl 7.81.0

二、前置条件

实例就绪：curl -s http://localhost:13904/-/health/ready/ 实测 200；
已持有管理员 API Token（初始引导 Token 或管理台创建的 Token）；
已知一个授权 Flow 的 UUID（Provider 创建类接口必填，取法见 6.3）。

三、API 总览

协议与风格：REST + JSON，路径前缀 /api/v3；
版本查询（实测）：

curl -s -H "Authorization: Bearer <Token>" http://localhost:13904/api/v3/admin/version/

{"version_current":"2026.8.4","version_latest":"2026.8.4","version_latest_valid":true,"build_hash":"","outdated":false,"outpost_outdated":false}

认证方式两种（均实测）：① 静态 API Token（Authorization: Bearer <token>）；② OAuth2 client_credentials 机器对机器 token（经 /application/o/token/ 签发，见 6.2）；
分页约定：所有列表接口返回 pagination 对象（next/previous/count/current/total_pages/start_index/end_index）+ results 数组；
错误约定：鉴权失败 403（{"detail":"Token invalid/expired"}）、对象不存在 404（{"detail":"No User matches the given query."}）、校验失败 400（字段级错误对象）——三种均实测留档。

四、认证与首次调用

4.1 静态 Token 方式

curl -s -H "Authorization: Bearer bootstrap-token-akadmin-2026" \
  http://localhost:13904/api/v3/root/config/

实测返回节选：

{
    "capabilities": ["can_save_media","can_save_reports","can_asn","can_geo_ip","can_impersonate","is_enterprise","can_agent_self_service"],
    "cache_timeout": 300
}

错误 Token 实测：

curl -s -H "Authorization: Bearer wrong-token" http://localhost:13904/api/v3/core/users/

{"detail":"Token invalid/expired"}

（HTTP 状态码实测 403；完全不携带 Token 亦为 403。）

4.2 机器对机器（client_credentials）方式

需先有 OAuth2 Provider（grant_types 含 client_credentials，创建见 6.4）与绑定的 Application。签发（Basic 认证携带 client_id:client_secret）：

curl -s -u "<client_id>:<client_secret>" -X POST \
  http://localhost:13904/application/o/token/ \
  -d "grant_type=client_credentials&scope=openid goauthentik.io/api"

实测返回：

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "scope": "",
    "expires_in": 3600,
    "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

实测发现：该 token 默认无 API 权限——GET /api/v3/core/users/me/ 实测 403；把系统自动创建的 service account 用户（实测用户名 ak-demo-api-provider-client_credentials）加入授权分组后同请求返回 200，身份确认：

username = ak-demo-api-provider-client_credentials | type = service_account

两种方式选型：交互脚本/管理员自动化用静态 Token；服务间调用用 M2M（可独立吊销、走协议审计）。

五、分页/过滤/排序通用约定

实测样例（users 列表，带过滤与默认分页）：

curl -s -H "Authorization: Bearer <Token>" \
  "http://localhost:13904/api/v3/core/users/?username=qdemo"

{
    "pagination": {"next": 0, "previous": 0, "count": 1, "current": 1, "total_pages": 1, "start_index": 1, "end_index": 1},
    "results": [{"pk": 6, "username": "qdemo", "email": "qdemo@example.com"}]
}

分页参数：page、page_size；
过滤：各域自带字段过滤（如 username、name、type、slug）；
排序：ordering=<字段名>（flows 绑定按 ordering=order 实测可用）；
搜索：search=<关键词>（outpost 服务账号检索实测可用）。

六、各 API 域详解

6.1 users 域（/api/v3/core/users/）

创建（实测）：

curl -s -X POST -H "Authorization: Bearer <Token>" -H "Content-Type: application/json" \
  http://localhost:13904/api/v3/core/users/ \
  -d '{"username":"qdemo","name":"Q Demo","email":"qdemo@example.com","path":"users","type":"internal"}'

{
    "pk": 6,
    "username": "qdemo",
    "name": "Q Demo",
    "email": "qdemo@example.com",
    "type": "internal",
    "is_active": true,
    "uid": "ccff671549b3f48eaa37c28f9982ce6d4123323e429b967ffb777df8bb5cb4a4"
}

读取单个（实测 GET /api/v3/core/users/6/ 返回同结构对象）；修改（实测）：

curl -s -X PATCH -H "Authorization: Bearer <Token>" -H "Content-Type: application/json" \
  http://localhost:13904/api/v3/core/users/6/ \
  -d '{"name":"Q Demo Updated"}'

{"name": "Q Demo Updated"}

不存在的主键（实测 GET /api/v3/core/users/99999/）：

{"detail":"No User matches the given query."}

（HTTP 404。）缺必填字段（实测 POST 空体）：

{"username":["This field is required."],"name":["This field is required."]}

（HTTP 400。）删除：DELETE /api/v3/core/users/6/（成功返回 204，实测同族接口 204 行为）。

6.2 applications 域（/api/v3/core/applications/）

创建并绑定已有 Provider（实测）：

curl -s -X POST -H "Authorization: Bearer <Token>" -H "Content-Type: application/json" \
  http://localhost:13904/api/v3/core/applications/ \
  -d '{"name":"Demo API","slug":"demo-api","provider":1}'

{
    "pk": "fc3f388c-3864-4084-8006-0fddec16e727",
    "name": "Demo API",
    "slug": "demo-api",
    "provider_obj": {"name": "demo-api-provider"}
}

列表（实测 GET /api/v3/core/applications/，pagination.count 含新建应用）；修改用 PATCH /api/v3/core/applications/demo-api/（主键可用 slug）；删除 DELETE /api/v3/core/applications/demo-api/ 返回 204。

6.3 flows 域（/api/v3/flows/）

列出全部流程（实测）：

curl -s -H "Authorization: Bearer <Token>" \
  "http://localhost:13904/api/v3/flows/instances/?page_size=100"

实测 results 节选（共 15 条出厂流程）：

default-authentication-flow                 authentication
default-provider-authorization-explicit-consent  authorization
default-provider-authorization-implicit-consent  authorization
default-invalidation-flow                   invalidation
default-source-enrollment                   enrollment

读取单个（拿 UUID 供 Provider 用，实测）：

curl -s -H "Authorization: Bearer <Token>" \
  http://localhost:13904/api/v3/flows/instances/default-provider-authorization-implicit-consent/

{"pk": "f088dd04-3890-45c7-90b3-130b7c87f4ed", "slug": "default-provider-authorization-implicit-consent", "designation": "authorization", ...}

创建自定义 Flow 与阶段绑定（实测，2026.x 绑定端点为 /flows/bindings/）：

curl -s -X POST -H "Authorization: Bearer <Token>" -H "Content-Type: application/json" \
  http://localhost:13904/api/v3/flows/bindings/ \
  -d '{"stage":"ff65ac71-57f7-4ec5-862b-bf38578ec11e","order":0,"target":"2316e129-928b-48c6-9e9c-2bd4f4264020"}'

{"pk": "57bfc595-75e3-4c46-83ba-a0f7cc443323", "order": 0}

流程执行调试通道：GET/POST /api/v3/flows/executor/<slug>/（完整走通实录见《Authentik 2026.8 核心原理详解》第三节）。

6.4 providers 域（/api/v3/providers/）

创建 OAuth2 Provider（实测；注意 2026.x 格式：flow 传 UUID、redirect_uris 传对象数组）：

curl -s -X POST -H "Authorization: Bearer <Token>" -H "Content-Type: application/json" \
  http://localhost:13904/api/v3/providers/oauth2/ \
  -d '{"name":"demo-api-provider","authorization_flow":"f088dd04-3890-45c7-90b3-130b7c87f4ed","invalidation_flow":"4f091897-5824-43c7-9397-cd901fd2a3d1","client_type":"confidential","grant_types":["client_credentials"],"access_token_validity":"hours=1","redirect_uris":[{"matching_mode":"strict","url":"http://localhost:9009/callback"}]}'

实测返回关键字段：

{
    "pk": 1,
    "name": "demo-api-provider",
    "client_id": "bw1sAlVoDMyNjZ8ge5LBpAJX2Y1lVnf4TApfXNOF",
    "client_secret": "<仅创建时返回一次>",
    "sub_mode": "hashed_user_id",
    "access_token_validity": "hours=1"
}

读取单个（实测 GET /api/v3/providers/oauth2/1/）：

{
    "pk": 1,
    "name": "demo-api-provider",
    "client_id": "bw1sAlVoDMyNjZ8ge5LBpAJX2Y1lVnf4TApfXNOF",
    "client_type": "confidential",
    "grant_types": ["client_credentials"],
    "access_token_validity": "hours=1",
    "sub_mode": "hashed_user_id"
}

更新 property_mappings（实测 PATCH 同路径，响应中映射列表随之更新）。Proxy Provider（实测创建返回 pk=2、external_host=http://demo.internal:8080、mode=proxy）与 SAML Provider（实测创建返回 pk=3、sp_binding=post）同域操作，路径分别为 /providers/proxy/、/providers/saml/。

6.5 outposts 域（/api/v3/outposts/）

实例列表（实测）：

curl -s -H "Authorization: Bearer <Token>" http://localhost:13904/api/v3/outposts/instances/

{
    "results": [
        {"pk": "058b8df5-1f62-4a36-8a98-69251630c4b4", "name": "authentik Embedded Outpost", "type": "proxy", "providers": [], "token_identifier": "ak-outpost-058b8df5-1f62-4a36-8a98-69251630c4b4-api"},
        {"pk": "e4a7eafd-7655-4bc5-b754-009d97f5a2f5", "name": "demo-proxy-outpost", "type": "proxy", "providers": [2]}
    ]
}

创建（实测，绑定 Provider 2）：

curl -s -X POST -H "Authorization: Bearer <Token>" -H "Content-Type: application/json" \
  http://localhost:13904/api/v3/outposts/instances/ \
  -d '{"name":"demo-proxy-outpost","type":"proxy","providers":[2],"config":{"log_level":"info"}}'

{"pk": "e4a7eafd-7655-4bc5-b754-009d97f5a2f5", "name": "demo-proxy-outpost", "type": "proxy", "providers": [2]}

健康查询（实测 GET /api/v3/outposts/instances/<pk>/health/；嵌入式实例有 last_seen/version，未部署的手动实例返回 []）：

[{"uid": "e5504b99-9159-4a56-ae1c-b7a3ffdb300e", "last_seen": "2026-10-17T20:09:30.909343Z", "version": "2026.8.4", "version_should": "2026.8.4", "version_outdated": false, "hostname": "52fbdfc47034"}]

实测注意：/outposts/proxy/（Outpost 侧拉取代理配置的数据面端点）对管理员 Token 返回 403——{"detail":"You do not have permission to perform this action."}，它仅供 Outpost 服务账号调用。

七、常见问题

Q1：404 返回 HTML 而不是 JSON？ 请求了不存在的 API 路径（被前端路由接住）。2026.x 实测变化：/flowstagebindings/ → /flows/bindings/，/tenants/tenants/ → /core/brands/，/core/users/<pk>/groups/ 不存在（用 POST /core/groups/<uuid>/add_user/）。以 GET /api/v3/schema/ 为准核对路径。

Q2：Provider 创建报 400 字段错误？ 三类实测坑：authorization_flow 必须传 UUID（报错 “default-provider-authorization-implicit-consent” is not a valid UUID.）；invalidation_flow 必填；redirect_uris 必须为对象数组（报错 Invalid data. Expected a dictionary, but got str. 的变体）。

Q3：M2M token 调管理 API 返回 Token invalid/expired？ 两步排查：token 是否过期（expires_in 实测 3600 秒）；服务账号是否已加入有权限的分组（实测入组前 403、入组后 200）。

Q4：如何批量探索接口？ GET /api/v3/schema/（实测 1.8MB YAML、607 路径），或浏览器打开 /api/v3/schema/swagger-ui/ 形态的交互页按域调试。

八、参考链接

API 文档：https://docs.goauthentik.io/docs/api/
本机 Schema：http://<服务器IP>:13904/api/v3/schema/
Token 概念：https://docs.goauthentik.io/docs/add-secure-apps/api/tokens
本系列：《Authentik 2026.8 核心原理详解》《Authentik Docker Compose 部署指南》