跳到主内容

Casdoor 公共 API

Casdoor 前端网页用户界面是一个用 React 开发的SPA（单页应用程序）。 React前端使用了Go后端代码暴露的Casdoor RESTful API。 这个RESTful API被称为Casdoor Public API。 换句话说，通过HTTP调用，你可以像Casdoor网页界面本身一样做任何事情。 没有其他限制。 以下人员可以利用该API：

  • Casdoor的前端
  • Casdoor 客户端 SDK（例如，casdoor-go-sdk）
  • 来自应用程序一侧的任何其他自定义代码

Casdoor Public API的完整参考可以在Swagger上找到：https://door.casdoor.com/swagger。 这些Swagger文档是使用Beego的Bee工具自动生成的。 如果你想要自己生成Swagger文档，请参见：如何生成swagger文件

API Response Language​

Casdoor APIs support internationalized responses. The default response language is English. To receive error messages and other text content in your preferred language, include the Accept-Language header in your API requests:

# Example: Get error messages in French
curl -X GET https://door.casdoor.com/api/get-account \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept-Language: fr"

Supported language codes include en, zh, es, fr, de, ja, ko, and more. For a complete list and more details, see the Internationalization documentation.

Machine-to-Machine (M2M) Authentication​

Machine-to-machine (M2M) authentication is designed for scenarios where services, applications, or backend systems need to authenticate and communicate with APIs without user interaction. This is particularly useful for:

  • Backend services calling Casdoor APIs programmatically
  • CLI tools that need to interact with your APIs using access tokens
  • B2B enterprise scenarios where organizations need to generate tokens for API access (e.g., admin tokens for management operations, read tokens for data access)
  • Automated processes such as scheduled jobs, data synchronization, or system integrations
  • Microservices that need to authenticate with each other

Casdoor supports M2M authentication through the following methods:

  1. Client Credentials Grant (OAuth 2.0): The recommended approach for M2M scenarios. This uses the Client Credentials Grant flow where applications authenticate using their Client ID and Client Secret to obtain access tokens. See the OAuth Client Credentials Grant documentation for details on obtaining tokens via this flow.

  2. Direct API Authentication with Client ID and Secret: Use the application's credentials directly in API calls (see method #2 below).

Use Cases for M2M Authentication​

  • Organization-level API access: In B2B scenarios, you can create a Casdoor application for each organization. The application's client credentials provide admin-level permissions for that organization, enabling them to manage their users, generate tokens, and access organizational resources independently.

  • Token generation for downstream services: Generate access tokens programmatically (using Client Credentials Grant) that can be distributed to CLI tools, read-only services, or other applications that need scoped access to your APIs.

  • Service-to-service authentication: Backend services can authenticate as an "application" rather than as a user, with permissions equivalent to the organization admin.

如何使用Casdoor Public API进行身份验证​

1. 通过Access token​

我们可以使用为经过身份验证的用户授予的访问令牌，以用户自身的身份调用Casdoor Public API。

如何获取访问令牌？​

应用程序可以在OAuth登录过程结束时（也就是通过代码和状态获取令牌）获取Casdoor用户的访问令牌。 API调用的权限将与用户的权限相同。

以下示例展示了如何通过casdoor-go-sdk在Go中调用GetOAuthToken()函数。

func (c *ApiController) Signin() {
    code := c.Input().Get("code")
    state := c.Input().Get("state")

    token, err := casdoorsdk.GetOAuthToken(code, state)
    if err != nil {
        c.ResponseError(err.Error())
        return
    }

    claims, err := casdoorsdk.ParseJwtToken(token.AccessToken)
    if err != nil {
        c.ResponseError(err.Error())
        return
    }

    if !claims.IsAdmin {
        claims.Type = "chat-user"
    }

    err = c.addInitialChat(&claims.User)
    if err != nil {
        c.ResponseError(err.Error())
        return
    }

    claims.AccessToken = token.AccessToken
    c.SetSessionClaims(claims)

    c.ResponseOk(claims)
}

所有授予的访问令牌也可以通过管理员用户在Tokens页面上的web UI进行访问。 例如，访问：https://door.casdoor.com/tokens 以查看演示站点。

如何进行身份验证？​

  1. HTTP GET 参数，其URL格式为：

    /page?access_token=<访问令牌>

    演示站点示例：https://door.casdoor.com/api/get-global-providers?access_token=eyJhbGciOiJSUzI1NiIs

  2. HTTP Bearer令牌，HTTP头格式是：

    Authorization: Bearer <访问令牌>

2. By Client ID and Client secret (Machine-to-Machine)​

This method is the primary approach for machine-to-machine (M2M) authentication. It allows applications, services, or backend systems to authenticate with Casdoor APIs without any user interaction.

如何获取客户端ID和密钥？​

应用程序编辑页面（例如，https://door.casdoor.com/applications/casbin/app-vue-python-example）将显示应用程序的客户端ID和密钥。 This authentication method is useful when you want to call the API as a "machine", "application", or a "service" instead of a user. The permissions for the API calls will be the same as the application (equivalent to the admin of the organization).

Use cases​

  • Service authentication: Backend services calling Casdoor APIs programmatically
  • Organization management: In B2B scenarios, create an application per organization to enable them to manage users and generate tokens independently
  • Token generation: Obtain access tokens via the OAuth Client Credentials Grant flow for distribution to CLI tools or other services

如何进行身份验证？​

  1. HTTP GET 参数，其URL格式为：

    /page?clientId=<客户端ID>&clientSecret=<客户端密钥>

    演示站点示例：https://door.casdoor.com/api/get-global-providers?clientId=294b09fbc17f95daf2fe&clientSecret=dd8982f7046ccba1bbd7851d5c1ece4e52bf039d

  2. HTTP 基本认证，其HTTP头格式为：

    Authorization: Basic <客户端ID和客户端密钥以单个冒号":"连接的Base64编码>

如果你不熟悉Base64编码，你可以使用一个库来完成这个任务，因为HTTP Basic Authentication是一个被许多地方支持的流行标准。

Obtaining access tokens with Client Credentials​

For machine-to-machine scenarios where you need to obtain an access token (rather than using client credentials directly), use the OAuth 2.0 Client Credentials Grant flow:

  1. Make a POST request to https://<CASDOOR_HOST>/api/login/oauth/access_token with:

    {
        "grant_type": "client_credentials",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET"
    }

  2. You will receive an access token response:

    {
        "access_token": "eyJhb...",
        "token_type": "Bearer",
        "expires_in": 10080,
        "scope": "openid"
    }

  3. Use the access_token to call Casdoor APIs (see method #1 above).

For more details, see the Client Credentials Grant documentation.

信息

For B2B Enterprises: You can create separate Casdoor applications for each of your customer organizations. Each application has its own client_id and client_secret, which your customers can use to:

  • Authenticate as their organization (with admin privileges)
  • Generate access tokens for their users or services
  • Manage their organization's users and permissions independently
  • Integrate your APIs into their systems without UI-based login flows

This approach allows you to delegate organization management to your customers while maintaining security and isolation between different organizations.

3. 通过Access key和Access secret​

我们可以使用Casdoor用户的访问密钥和访问秘密来调用Casdoor Public API作为用户本身。 访问密钥和访问秘密可以由管理员或用户本人在用户设置页面中配置。 update-user API也可以被调用来更新这些字段。 API 调用的权限将与用户的权限相同。

如何进行身份验证？​

  1. 在账户设置页面中创建一对 accessKey 和 accessSecret。

  2. HTTP GET 参数，其URL格式为：

    /page?accessKey=<The user's access key>&accessSecret=<the user's access secret>"

演示站点示例：https://door.casdoor.com/api/get-global-providers?accessKey=b86db9dc-6bd7-4997-935c-af480dd2c796/admin&accessSecret=79911517-fc36-4093-b115-65a9741f6b14

User Api Key

curl --location 'http://door.casdoor.com/api/user?accessKey=b86db9dc-6bd7-4997-935c-af480dd2c796&accessSecret=79911517-fc36-4093-b115-65a9741f6b14'

4. 通过username和password​

注意事项

这种认证方法并不安全，仅为了兼容性或演示目的而保留在此。 我们建议使用前三种身份验证方法。

会发生什么？​

用户凭证将会以GET参数的形式在请求URL中暴露出来。 此外，如果你使用的是HTTP而不是HTTPS，用户的凭证将会被网络以明文形式嗅探。

我们可以使用Casdoor用户的用户名和密码来以用户自身的身份调用Casdoor Public API。 用户名采用的格式为<用户的组织名称>/<用户名>。 API调用的权限将与用户相同。

如何进行身份验证？​

  1. HTTP GET参数，URL格式为：

    /page?username=<用户的组织名称>/<用户名>&password=<用户的密码>"

演示站点示例：https://door.casdoor.com/api/get-global-providers?username=built-in/admin&password=123

SSO Logout​

The SSO logout endpoint /api/sso-logout allows you to log out a user from all applications in an organization simultaneously. When called, this endpoint will:

  • Delete all active sessions for the user across all applications
  • Expire all access tokens issued to the user
  • Clear the current session and token

This is particularly useful when you need to ensure a user is completely logged out from all services, such as during security incidents or when implementing organization-wide logout policies.

Endpoint​

GET or POST /api/sso-logout

Authentication​

This endpoint requires the user to be authenticated. You can use any of the authentication methods described in the How to authenticate section above.

Example Request​

# Using access token
curl -X POST https://door.casdoor.com/api/sso-logout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Using session cookie
curl -X POST https://door.casdoor.com/api/sso-logout \
  --cookie "casdoor_session_id=abc123def456"

Response​

{
  "status": "ok",
  "msg": "",
  "data": ""
}

CORS (Cross-Origin Resource Sharing)​

Casdoor implements flexible CORS handling to allow secure cross-origin API requests. The server validates the Origin header and returns appropriate Access-Control-Allow-Origin headers based on the following rules:

Allowed origins:

  • Origins matching your application's redirect URIs (configured in the application settings)
  • Origins matching the Casdoor server's own hostname
  • The configured origin in Casdoor's settings
  • Special endpoint exceptions: requests to /api/login/oauth/access_token and /api/userinfo endpoints, and requests with origin appleid.apple.com

How it works:

When you make a cross-origin API request, Casdoor validates the origin through multiple checks: localhost/intranet addresses, matching redirect URIs in any application, matching the server's hostname, or configured origins. If any validation passes, the server includes CORS headers in the response allowing the request. For preflight OPTIONS requests, Casdoor returns appropriate headers including allowed methods (POST, GET, OPTIONS, DELETE) and credentials support.

Configuration:

To enable CORS for your application, add your frontend's origin to the application's Redirect URIs in the Casdoor admin panel. This allows your application to make authenticated API calls from the browser.