Перейти до основного вмісту

Публічний API Casdoor

Веб-інтерфейс фронтенду Casdoor - це SPA (Single-Page Application), розроблений на React. Фронтенд на React використовує RESTful API Casdoor, який надається кодом бекенду на Go. Цей RESTful API називається Casdoor Public API. Іншими словами, за допомогою HTTP-запитів ви можете робити все так само, як і сам веб-інтерфейс Casdoor. Немає інших обмежень. API може бути використаний наступним чином:

  • Фронтенд Casdoor
  • Клієнтські SDK Casdoor (наприклад, casdoor-go-sdk)
  • Будь-який інший налаштований код зі сторони додатку

Повний довідник для Casdoor Public API можна знайти на Swagger: https://door.casdoor.com/swagger. Ці документи Swagger автоматично генеруються за допомогою інструменту Bee від Beego. Якщо ви хочете самостійно згенерувати документи 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 як сам користувач.

Як отримати токен доступу?​

Додаток може отримати токен доступу для користувача Casdoor в кінці процесу OAuth-авторизації (тобто отримати токен за допомогою коду та стану). Дозволи для API-викликів будуть такими ж, як у користувача.

Нижче наведені приклади показують, як викликати функцію GetOAuthToken() на Go через casdoor-go-sdk.

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. Наприклад, відвідайте: https://door.casdoor.com/tokens для демонстраційного сайту.

Як автентифікуватися?​

  1. HTTP GET параметр, формат URL:

    /page?access_token=<The access token>

    Приклад демонстраційного сайту: https://door.casdoor.com/api/get-global-providers?access_token=eyJhbGciOiJSUzI1NiIs

  2. HTTP Bearer token, формат HTTP-заголовка:

    Authorization: Bearer <The access token>

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.

Як отримати client ID та secret?​

Сторінка редагування додатку (наприклад, https://door.casdoor.com/applications/casbin/app-vue-python-example) покаже client ID та secret для додатку. 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=<The client ID>&clientSecret=<the client secret>

    Приклад демонстраційного сайту: https://door.casdoor.com/api/get-global-providers?clientId=294b09fbc17f95daf2fe&clientSecret=dd8982f7046ccba1bbd7851d5c1ece4e52bf039d

  2. HTTP Basic Authentication, формат HTTP-заголовка:

    Authorization: Basic <The Base64 encoding of client ID and client secret joined by a single colon ":">

Якщо ви не знайомі з кодуванням 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​

Ми можемо використовувати access key та access secret користувача Casdoor для виклику Casdoor Public API як сам користувач. Access key та access secret можна налаштувати на сторінці налаштувань користувача адміністратором або самим користувачем. API update-user також може бути викликаний для оновлення цих полів. Дозволи для API-викликів будуть такими ж, як у користувача.

Як автентифікуватися?​

  1. Create a pair of accessKey and accessSecret in account setting page.

  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=<The user's organization name>/<The user name>&password=<the user's password>"

Приклад демонстраційного сайту: https://door.casdoor.com/api/get-global-providers?username=built-in/admin&password=123