openapi: 3.1.0
info:
  title: Zitadel Management Applications Projects API
  description: The Zitadel Management API provides comprehensive identity infrastructure management including users, organizations, projects, applications, roles, policies, and identity providers. Accessible via REST at /management/v1/ with gRPC transcoding support. Zitadel is an open source identity platform supporting OAuth 2.0, OIDC, SAML, SCIM, FIDO2, and passkeys.
  version: 1.0.0
  contact:
    name: Zitadel
    url: https://zitadel.com
  license:
    name: GNU AGPLv3
    url: https://github.com/zitadel/zitadel/blob/main/LICENSE
  termsOfService: https://zitadel.com/legal/terms-of-service
servers:
- url: https://{instance}.zitadel.cloud
  description: Zitadel Cloud instance
  variables:
    instance:
      default: your-instance
      description: Your Zitadel cloud instance name
- url: https://{custom-domain}
  description: Self-hosted Zitadel instance
  variables:
    custom-domain:
      default: localhost:8080
      description: Your self-hosted Zitadel domain
security:
- bearerAuth: []
tags:
- name: Projects
  description: Manage projects and project grants
paths:
  /management/v1/projects:
    post:
      operationId: createProject
      summary: Zitadel Create Project
      description: Create a new project within the organization for grouping applications and roles.
      tags:
      - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '200':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
  /management/v1/projects/_search:
    post:
      operationId: listProjects
      summary: Zitadel List Projects
      description: Search for projects within the organization.
      tags:
      - Projects
      responses:
        '200':
          description: List of projects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProjectsResponse'
  /management/v1/projects/{projectId}:
    get:
      operationId: getProjectById
      summary: Zitadel Get Project by ID
      description: Retrieve a project by its unique identifier.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Project details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
    put:
      operationId: updateProject
      summary: Zitadel Update Project
      description: Update project configuration and settings.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '200':
          description: Project updated successfully
    delete:
      operationId: removeProject
      summary: Zitadel Remove Project
      description: Permanently delete a project and all its applications and roles.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Project removed successfully
components:
  schemas:
    CreateProjectRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        projectRoleAssertion:
          type: boolean
        projectRoleCheck:
          type: boolean
        hasProjectCheck:
          type: boolean
    ListDetails:
      type: object
      properties:
        totalResult:
          type: string
        processedSequence:
          type: string
        timestamp:
          type: string
          format: date-time
    ProjectResponse:
      type: object
      properties:
        project:
          $ref: '#/components/schemas/Project'
    ListProjectsResponse:
      type: object
      properties:
        details:
          $ref: '#/components/schemas/ListDetails'
        result:
          type: array
          items:
            $ref: '#/components/schemas/Project'
    Project:
      type: object
      properties:
        id:
          type: string
        details:
          $ref: '#/components/schemas/ObjectDetails'
        name:
          type: string
        state:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
        projectRoleAssertion:
          type: boolean
        projectRoleCheck:
          type: boolean
        hasProjectCheck:
          type: boolean
        privateLabelingSetting:
          type: string
    ObjectDetails:
      type: object
      properties:
        sequence:
          type: string
        creationDate:
          type: string
          format: date-time
        changeDate:
          type: string
          format: date-time
        resourceOwner:
          type: string
  parameters:
    ProjectId:
      name: projectId
      in: path
      required: true
      description: Unique identifier of the project
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: Zitadel API Reference
  url: https://zitadel.com/docs/apis/introduction