Passer au contenu principal

API publique de Casdoor

L'interface utilisateur web frontend de Casdoor est une SPA (Single-Page Application) développée en React. Le frontend React consomme l'API RESTful de Casdoor exposée par le code backend en Go. Cette API RESTful est appelée Casdoor Public API. En d'autres termes, avec des appels HTTP, vous pouvez tout faire comme le fait l'interface utilisateur web de Casdoor elle-même. Il n'y a pas d'autres limitations. L'API peut être utilisée par les suivants :

  • Frontend de Casdoor
  • SDKs clients de Casdoor (par exemple, casdoor-go-sdk)
  • Tout autre code personnalisé du côté de l'application

La référence complète pour l'Casdoor Public API peut être trouvée sur Swagger : https://door.casdoor.com/swagger. Ces documents Swagger sont générés automatiquement en utilisant l'outil Bee de Beego. Si vous souhaitez générer les documents Swagger par vous-même, voir : Comment générer le fichier 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.

Comment s'authentifier avec l'Casdoor Public API​

1. Par Access token​

Nous pouvons utiliser le token d'accès accordé à un utilisateur authentifié pour appeler l'Casdoor Public API comme l'utilisateur lui-même.

Comment obtenir le token d'accès ?​

L'application peut obtenir le token d'accès pour l'utilisateur de Casdoor à la fin du processus de connexion OAuth (alias obtenir le token par code et état). Les permissions pour les appels API seront les mêmes que celles de l'utilisateur.

L'exemple ci-dessous montre comment appeler la fonction GetOAuthToken() en Go via 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)
}

Tous les tokens d'accès accordés peuvent également être consultés via l'interface utilisateur web par un utilisateur administrateur dans la page Tokens. Par exemple, visitez : https://door.casdoor.com/tokens pour le site de démonstration.

Comment s'authentifier ?​

  1. Paramètre GET HTTP, le format de l'URL est :

    /page?access_token=<The access token>

    Exemple de site de démonstration : https://door.casdoor.com/api/get-global-providers?access_token=eyJhbGciOiJSUzI1NiIs

  2. Token porteur HTTP, le format de l'en-tête HTTP est :

    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.

Comment obtenir l'ID client et le secret ?​

La page d'édition de l'application (par exemple, https://door.casdoor.com/applications/casbin/app-vue-python-example) affichera l'ID client et le secret pour une application. 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

Comment s'authentifier ?​

  1. Paramètre GET HTTP, le format de l'URL est :

    /page?clientId=<The client ID>&clientSecret=<the client secret>

    Exemple de site de démonstration : https://door.casdoor.com/api/get-global-providers?clientId=294b09fbc17f95daf2fe&clientSecret=dd8982f7046ccba1bbd7851d5c1ece4e52bf039d

  2. Authentification de base HTTP, le format de l'en-tête HTTP est :

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

Si vous n'êtes pas familier avec l'encodage Base64, vous pouvez utiliser une bibliothèque pour le faire car l'Authentification de base HTTP est une norme populaire prise en charge par de nombreux endroits.

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.

info

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. Par Access key et Access secret​

Nous pouvons utiliser la clé d'accès et le secret d'accès pour un utilisateur Casdoor pour appeler l'Casdoor Public API comme l'utilisateur lui-même. La clé d'accès et le secret d'accès peuvent être configurés dans la page des paramètres de l'utilisateur par un administrateur ou l'utilisateur lui-même. L'API update-user peut également être appelée pour mettre à jour ces champs. Les permissions pour les appels API seront les mêmes que celles de l'utilisateur.

Comment s'authentifier ?​

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

  2. Paramètre GET HTTP, le format de l'URL est :

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

Exemple de site de démonstration : 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. Par username et password​

prudence

Cette méthode d'authentification n'est pas sûre et est conservée ici uniquement à des fins de compatibilité ou de démonstration. Nous recommandons d'utiliser les trois méthodes d'authentification précédentes à la place.

Que se passera-t-il ?​

Les informations d'identification de l'utilisateur seront exposées en tant que paramètres GET dans l'URL de la requête. De plus, les informations d'identification de l'utilisateur pourront être interceptées en texte clair par le réseau si vous utilisez HTTP au lieu de HTTPS.

Nous pouvons utiliser le nom d'utilisateur et le mot de passe d'un utilisateur Casdoor pour appeler l'Casdoor Public API comme l'utilisateur lui-même. Le nom d'utilisateur prend le format de <Le nom de l'organisation de l'utilisateur>/<Le nom de l'utilisateur>. Les permissions pour les appels API seront les mêmes que celles de l'utilisateur.

Comment s'authentifier ?​

  1. Paramètre GET HTTP, le format de l'URL est :

    /page?username=<The user's organization name>/<The user name>&password=<the user's password>"

Exemple de site de démonstration : https://door.casdoor.com/api/get-global-providers?username=built-in/admin&password=123

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.