Casdoor API 实战教程：5 步完成第一次接口调用-育师

Casdoor API 实战教程：5 步完成第一次接口调用

【免费下载链接】casdoorAn open-source Agent-first Identity and Access Management (IAM) /LLM MCP & agent gateway and auth server with web UI supporting OpenClaw, MCP, OAuth, OIDC, SAML, CAS, LDAP, SCIM, WebAuthn, TOTP, MFA, Face ID, Google Workspace, Azure AD项目地址: https://gitcode.com/gh_mirrors/ca/casdoor

Casdoor 是一个开源的身份认证与访问管理（IAM）平台，支持 OAuth、OIDC、SAML、LDAP、WebAuthn 等协议，还能给 AI 智能体和 MCP 工具当认证网关。这篇文章围绕 Casdoor API 调用展开：先花 5 步拿到第一个访问令牌，再弄懂响应格式和参数约定，最后把登录、用户、权限三类接口用到真实业务里。

🚀 拿到第一个访问令牌：5 步

启动服务。默认端口是 8000，管理页面地址 http://localhost:8000，默认账号 admin，默认密码 123。
打开测试页。浏览器访问 http://localhost:8000/swagger，这是内置的接口调试页面，所有接口分组列出，可以直接在页面上填参数试调。
发起登录请求。找到 POST /api/login，四个关键入参：application（应用名，如 built-in-app）、username、password、organization（组织名，如 built-in）。
确认响应。看到"status":"ok"，且data里有 accessToken 和 refreshToken，说明登录成功。
发起第一次调用。复制 accessToken，在请求头带上Authorization: Bearer <你的令牌>，请求GET /api/get-users?owner=built-in。看到用户列表 JSON，第一次 Casdoor API 调用就完成了。

不想翻页的话，一条命令也能发出去：

curl -X POST http://localhost:8000/api/login \ -d 'application=built-in-app&username=admin&password=123&organization=built-in&type=login'

🔍 先看到什么，再明白为什么

跑几个接口后你会注意到：不管成功失败，返回体长得都一样。

status：ok或error，判断成败看它，别只盯 HTTP 状态码；
msg：错误时的一句话说明，排查问题基本靠读它；
data：真正要的数据，列表接口里是数组，单条接口里是对象。

以 GET /api/get-users 为例，传上组织名 owner，拿到该组织下的用户列表，但邮箱、手机号这类敏感字段默认被遮掩。这是设计使然——防止普通令牌把整库隐私数据拉走。

为什么请求头必须带令牌

令牌是登录时签发的"通行证"。管理接口的处理顺序是：先验通行证，再执行操作，所以不带或过期都会被打回。常见放法有两种：请求头Authorization: Bearer <令牌>，或查询参数access_token。响应里的expireIn字段告诉你通行证还剩多少秒有效，过期后重新登录，或用 /api/login/oauth/refresh_token 换新令牌。

为什么几乎每个接口都要 owner 参数

Casdoor 按"多租户"方式存数据，owner 就是租户，也就是组织名。用户的完整身份是 owner/name，比如 built-in/admin。查询、新增、修改接口都要靠 owner 定位数据属于哪个组织。实战里最常见的"用户不存在"报错，多数是 owner 填错了。

参数和路由的完整约定，可以对照 routers/router.go 里的注册清单，或翻 controllers/ 下的具体实现。

把接口用到三个真实场景

下面的三个场景，覆盖了绝大多数 Casdoor API 调用的需求。

登录对接。自己不做登录页，把用户重定向到 Casdoor 的登录界面，登录完成后它会带着令牌跳回你的应用；后端拿这个令牌调 /api/userinfo 验证用户身份即可。关键参数：application（用哪个应用的身份页）、owner（组织）。

同步用户列表。定时调 GET /api/get-users 拉取用户进自己的系统。支持分页参数 pageSize 和 p，也支持按 field、value 过滤，不必每次全量拉取。

操作前权限校验。重要操作前调 POST /api/enforce，请求体是一个数组，比如["alice","article1","read"]，意思是"用户 alice 对 article1 有没有 read 权限"，返回直接给 true 或 false。

踩坑与速查

下表覆盖了 Casdoor API 调用中最容易撞上的四类错误：

现象	可能原因	处理办法
`status: error`，提示 Unauthorized	没带令牌或已过期	重新登录换新令牌；确认请求头写法是`Bearer <令牌>`
查不到用户	owner 是组织名，误填成了应用名	核对 owner 与账号所属组织是否一致
add-user 返回失败	必填字段缺失	请求体必须包含 owner、name、password
get-users 里邮箱手机号是遮掩值	默认脱敏	用管理员令牌，或走更新类接口拿完整数据

最常用的五个接口，先记这几行就够用了：

接口	方法	作用
/api/login	POST	登录，换取 accessToken 和 refreshToken
/api/get-users	GET	查用户列表，传 owner 指定组织
/api/add-user	POST	新建用户，请求体含 owner/name/password
/api/enforce	POST	单次权限判定，请求体为字符串数组
/api/health	GET	健康检查，方便运维监控探活