openapi: 3.1.0
info:
  title: Casdoor REST API
  description: |
    Casdoor is an open-source IAM/SSO platform exposing a RESTful API for managing
    users, organizations, applications, roles, permissions, sessions, and OIDC/OAuth
    flows. This best-effort OpenAPI is derived from the public Swagger published at
    https://door.casdoor.com/swagger/ and the documentation at https://casdoor.ai/docs/.
  version: "1.503.0"
  contact:
    name: Casdoor (Casbin)
    email: casbin@googlegroups.com
    url: https://casdoor.ai/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://door.casdoor.com
    description: Casdoor public demo instance
  - url: https://{host}
    description: Self-hosted Casdoor instance
    variables:
      host:
        default: localhost:8000
security:
  - bearerAuth: []
  - basicAuth: []
tags:
  - name: OIDC
    description: OpenID Connect discovery and JWKS endpoints
  - name: Authentication
    description: Login, callback, and device authorization
  - name: Users
    description: User CRUD and credential operations
  - name: Organizations
    description: Multi-tenant organization management
  - name: Applications
    description: OAuth/OIDC client applications
  - name: Roles
    description: Role-based access control
  - name: Permissions
    description: Casbin policy enforcement
paths:
  /.well-known/openid-configuration:
    get:
      tags: [OIDC]
      summary: OIDC discovery document
      operationId: getOidcDiscovery
      responses:
        '200':
          description: OIDC discovery metadata
          content:
            application/json:
              schema:
                type: object
  /.well-known/jwks:
    get:
      tags: [OIDC]
      summary: JSON Web Key Set
      operationId: getJwks
      responses:
        '200':
          description: JWKS containing signing keys
          content:
            application/json:
              schema:
                type: object
  /.well-known/webfinger:
    get:
      tags: [OIDC]
      summary: WebFinger user lookup
      operationId: getWebfinger
      parameters:
        - in: query
          name: resource
          required: true
          schema:
            type: string
      responses:
        '200':
          description: WebFinger metadata
  /api/login:
    post:
      tags: [Authentication]
      summary: Login a user
      operationId: login
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                application:
                  type: string
                organization:
                  type: string
                username:
                  type: string
                password:
                  type: string
                type:
                  type: string
      responses:
        '200':
          description: Authenticated session
  /api/signup:
    post:
      tags: [Authentication]
      summary: Sign up a new user
      operationId: signup
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Signup result
  /api/logout:
    post:
      tags: [Authentication]
      summary: Log out the current user
      operationId: logout
      responses:
        '200':
          description: Logout success
  /api/device-auth:
    post:
      tags: [Authentication]
      summary: OAuth 2.0 device authorization
      operationId: deviceAuth
      responses:
        '200':
          description: Device authorization response
  /api/get-users:
    get:
      tags: [Users]
      summary: List users in an organization
      operationId: getUsers
      parameters:
        - in: query
          name: owner
          required: true
          description: Organization name
          schema:
            type: string
      responses:
        '200':
          description: User list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
  /api/get-global-users:
    get:
      tags: [Users]
      summary: List all users across organizations
      operationId: getGlobalUsers
      responses:
        '200':
          description: Global user list
  /api/get-user:
    get:
      tags: [Users]
      summary: Get a single user
      operationId: getUser
      parameters:
        - in: query
          name: id
          required: true
          description: "Composite id in form owner/name"
          schema:
            type: string
      responses:
        '200':
          description: User
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /api/add-user:
    post:
      tags: [Users]
      summary: Create a user
      operationId: addUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Create result
  /api/update-user:
    post:
      tags: [Users]
      summary: Update a user
      operationId: updateUser
      parameters:
        - in: query
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Update result
  /api/delete-user:
    post:
      tags: [Users]
      summary: Delete a user
      operationId: deleteUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Delete result
  /api/check-user-password:
    post:
      tags: [Users]
      summary: Validate a user password
      operationId: checkUserPassword
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                organization:
                  type: string
                username:
                  type: string
                password:
                  type: string
      responses:
        '200':
          description: Password check result
  /api/get-organizations:
    get:
      tags: [Organizations]
      summary: List organizations
      operationId: getOrganizations
      parameters:
        - in: query
          name: owner
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Organization list
  /api/add-organization:
    post:
      tags: [Organizations]
      summary: Create an organization
      operationId: addOrganization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Organization'
      responses:
        '200':
          description: Create result
  /api/get-applications:
    get:
      tags: [Applications]
      summary: List applications
      operationId: getApplications
      parameters:
        - in: query
          name: owner
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Application list
  /api/get-application:
    get:
      tags: [Applications]
      summary: Get an application
      operationId: getApplication
      parameters:
        - in: query
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Application
  /api/add-application:
    post:
      tags: [Applications]
      summary: Create an application
      operationId: addApplication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Create result
  /api/get-roles:
    get:
      tags: [Roles]
      summary: List roles
      operationId: getRoles
      parameters:
        - in: query
          name: owner
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Role list
  /api/add-role:
    post:
      tags: [Roles]
      summary: Create a role
      operationId: addRole
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Create result
  /api/enforce:
    post:
      tags: [Permissions]
      summary: Casbin enforcement check
      operationId: enforce
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                v0:
                  type: string
                v1:
                  type: string
                v2:
                  type: string
      responses:
        '200':
          description: Enforcement decision
  /api/batch-enforce:
    post:
      tags: [Permissions]
      summary: Batch Casbin enforcement
      operationId: batchEnforce
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: Batch enforcement decisions
  /api/get-permissions:
    get:
      tags: [Permissions]
      summary: List permissions
      operationId: getPermissions
      parameters:
        - in: query
          name: owner
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Permission list
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    basicAuth:
      type: http
      scheme: basic
  schemas:
    User:
      type: object
      properties:
        owner:
          type: string
        name:
          type: string
        displayName:
          type: string
        email:
          type: string
        phone:
          type: string
        avatar:
          type: string
        password:
          type: string
        type:
          type: string
        createdTime:
          type: string
          format: date-time
    Organization:
      type: object
      properties:
        owner:
          type: string
        name:
          type: string
        displayName:
          type: string
        websiteUrl:
          type: string
        favicon:
          type: string
        passwordType:
          type: string
        passwordSalt:
          type: string
        countryCodes:
          type: array
          items:
            type: string